Suno song generation API: request fields
POST /api/v1/sonic/create accepts description mode or custom lyric mode. Every new request needs an account key and a saved UUID.
Endpoint and required headers#
Send UTF-8 JSON from your backend. The body must be at most 32,768 bytes. A browser request from another origin is rejected; this is a server integration API, not a cross-site browser endpoint.
POST https://sunoapi.com/api/v1/sonic/create
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_SAVED_UUIDRequest field reference#
Character limits below match this service’s current validation. The only supported mv values are sonic-v6, sonic-v6-wild and sonic-v6-mini. Do not assume identifiers from another provider are interchangeable.
| Field | Type / required | Meaning and limit |
|---|---|---|
| custom_mode | boolean; required | false: generate from a brief. true: use your lyrics. |
| mv | string; required | sonic-v6, sonic-v6-wild or sonic-v6-mini. |
| gpt_description_prompt | string; required when custom_mode=false | Nonempty musical brief; at most 400 characters. |
| prompt | string; required when custom_mode=true | Nonempty lyrics; at most 5,000 characters. |
| tags | string; optional in custom mode | Musical style; at most 1,000 characters. Defaults to empty. |
| title | string; optional in custom mode | Song name; at most 80 characters. Defaults to empty. |
| make_instrumental | boolean; optional | Request music without sung vocals. Defaults to false. |
Description mode#
Set custom_mode to false and put the musical brief in gpt_description_prompt. Describe mood, instrumentation, vocal character, and the intended listening context. Keep the brief at or below 400 characters.
{
"custom_mode": false,
"mv": "sonic-v6",
"gpt_description_prompt": "Dreamy indie pop, soft vocals, a hopeful chorus about starting over",
"make_instrumental": false
}Custom lyric mode#
Set custom_mode to true. The prompt field now contains your lyrics; tags describes the musical style. title names the song. Keep these roles separate so that instructions are not accidentally sung.
{
"custom_mode": true,
"mv": "sonic-v6",
"title": "Starting Over",
"tags": "indie pop, warm guitars, soft vocals",
"prompt": "[Verse]\nAn open door, a quiet street\n[Chorus]\nWe begin again",
"make_instrumental": false
}Model identifiers are API values#
The API uses Sonic identifiers in the mv field. This independent service supports sonic-v6, sonic-v6-wild, and sonic-v6-mini. Older model identifiers are rejected rather than silently mapped to a newer model. Model availability and account access can change; handle rejection responses.
Instrumental generation#
Set make_instrumental to true to request music without sung vocals. For the simplest instrumental workflow, use description mode and describe instruments, tempo, mood, and structure.
Keep a request record for each intentional song#
Before POST, persist the deployment base URL, account reference, UUID, exact JSON payload and your own lyric or scene revision. Add HTTP status and returned tracks to that record as responses arrive. Keep API keys in server-side secret storage rather than in the record. A new UUID means a new paid request, even when the brief is identical.
- For a lost response, query the saved UUID in the same deployment and account before retrying.
- A 409 does not replace the original payload. Retrieve the original task and compare your saved inputs.
- Use a fresh UUID only when you intentionally want another song. Editing a lyric, model or musical brief creates a new revision.
Reservation and response contract#
Each new UUID reserves 20 credits before provider submission. A create response can be pending (202), an already completed result (200), or a confirmed generation failure (200 with type: failed). Inspect both HTTP status and the response body. See task lifecycle for every response shape and recovery behavior.