---
title: "Generate music from a text description"
method: POST
path: "/v1/music"
tags: ["generation"]
---

# Generate music from a text description

`POST /v1/music`

## Request

- Base URL: `https://varosity.ai/api`
- URL: `https://varosity.ai/api/v1/music`
- Auth: HTTP bearer

Sync models (e.g. elevenlabs-music) return { trackId, audioUrl, sync: true }. Async models return { trackId, providerJobId, sync: false } with no audioUrl yet: poll POST /music/poll with { trackId } until status is 'succeeded' and audioUrl is set. Also available at /music. Requires generate:music scope.

## Request body

- object
  - `modelId` string, required: Music model ID from GET /v1/models (e.g. elevenlabs-music, lyria-2, suno-v4).
  - `prompt` string, required
  - `durationSec` integer, required: Capped by the model's maxDurationSec (above it: 400 duration_too_long). Lyria 2 always makes one 30-second clip.
  - `tags` string[]: Genre / mood tags.
  - `instrumental` boolean: No vocals (Suno).
  - `lyrics` string: Custom lyrics (Suno custom mode; the prompt becomes the style cue).
  - `title` string: Track title (Suno).

## Response `200`

Track generated (sync) or queued (async)

- object
  - `ok` boolean
  - `trackId` string, uuid
  - `audioUrl` string, uri: Present when sync is true.
  - `providerJobId` string: Present when sync is false.
  - `sync` boolean: false: poll POST /music/poll with { trackId }.

## Other responses

- `401`: Unauthorized
- `402`: Insufficient credits (insufficient_credits)
- `403`: Insufficient scope (insufficient_scope; needs generate:music)
- `429`: rate_limited (honour Retry-After) or daily_cap_exceeded (with spent_today_cents and daily_cap_cents; not retryable until the 00:00 UTC reset or a higher cap)
- `503`: spend_guard_error: the daily cap could not be checked

## Changes

- **2026-10-20** `81d0169a4897`: 10 info
  - added the new optional request property `instrumental`
  - added the new optional request property `lyrics`
  - added the new optional request property `tags`
  - added the new optional request property `title`
  - …6 more

[Operation history](https://skmtc.dev/varosity/apis/varosity-ai-api/changes/v1/music/post.md)

---

[API](https://skmtc.dev/varosity/apis/varosity-ai-api.md) · [All operations](https://skmtc.dev/varosity/apis/varosity-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varosity/apis/varosity-ai-api/revisions/81d0169a4897?raw)