Docs/Music/Text to Image

Suno Music· Text to Image

Text to Image

POSThttps://api.sozdai.ai/v1/media/generations

Pricing Model

Billed per successful media generation task. See the pricing page.

Execution Flow

Asynchronous submission model. Submitting requests queues background workers.

#Submit a task

Media generation is asynchronous: you get a task id immediately, without waiting.

bash

curl https://api.sozdai.ai/v1/media/generations \
  -H "Authorization: Bearer $CORRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "suno-music", "prompt": "calm ambient piano with soft melodies", "instrumental": true }'
# → { "id": "cmus7q0x9000108l3f5g2abcd", "status": "queued" }

#Request parameters

Parameter	Type	Required	Default	Description
`version`	string	No	`V5_5`	Suno engine version (the model is a parameter, not a separate endpoint). Default V5_5 (latest). Options: V5_5, V5, V4_5PLUS, V4_5, V4_5ALL, V4
`prompt`	string	Yes	—	Non-custom mode (default): a short idea, lyrics auto-written — max 500 chars. Custom mode (customMode: true): used as the exact lyrics — max 3000 chars on V4, 5000 on every other version.
`customMode`	boolean	No	`false`	Advanced control. When true, style+title required (and prompt as lyrics unless instrumental).
`instrumental`	boolean	No	`false`	Generate instrumental (no vocals).
`style`	string	No	—	Genre/mood (required in custom mode). Max 200 chars on V4, 1000 on every other version. e.g. Synthwave, Jazz, Lo-fi.
`title`	string	No	—	Track title (required in custom mode, max 80 chars).
`negativeTags`	string	No	—	Styles/traits to avoid. e.g. Heavy Metal.
`vocalGender`	string	No	—	Preferred vocal gender (custom mode only; best-effort). Options: m, f
`styleWeight`	number	No	—	How strongly to follow the style. Range 0–1, up to 2 decimals.
`weirdnessConstraint`	number	No	—	Experimental/creative deviation. Range 0–1, up to 2 decimals.
`audioWeight`	number	No	—	Balance weight for audio features vs. other factors. Range 0–1, up to 2 decimals.
`personaId`	string	No	—	Apply a Persona/Voice to the generation. Custom mode only.
`personaModel`	string	No	—	Persona type. Only available on V5 and V5_5. Options: style_persona, voice_persona
`callback_url`	string	No	—	Optional public http(s) URL. We POST the task result here the moment generation finishes (success or failure).

#Poll for the result

Generation runs asynchronously — the submit call returns immediately with a task id. Poll this endpoint with that id every few seconds until status becomes succeeded (result ready) or a terminal error (failed / timeout).

GEThttps://api.sozdai.ai/v1/media/generations/{id}

bash

# take the id from the submit response, then poll every ~3s
curl https://api.sozdai.ai/v1/media/generations/cmus7q0x9000108l3f5g2abcd \
  -H "Authorization: Bearer $CORRY_KEY"
# repeat until "status" is "succeeded" (or "failed" / "timeout")

#Response example

On submit

json

{
  "id": "cmus7q0x9000108l3f5g2abcd",
  "status": "queued",
  "type": "music",
  "model": "suno-music"
}

On success (after polling)

json

{
  "id": "cmus7q0x9000108l3f5g2abcd",
  "status": "succeeded",
  "type": "music",
  "model": "suno-music",
  "tracks": [
    {
      "id": "cmus7q9p1000208l3h6j3efgh",
      "title": "Paper Sunburn",
      "tags": "pop, upbeat, bright synth, punchy",
      "lyrics": "[Verse 1]\nCity lights on the dashboard glow\n...",
      "duration": 139.92,
      "streamUrl": "https://api.sozdai.ai/v1/media/stream/cmus7q9p1000208l3h6j3efgh/<token>",
      "audioUrl": "https://cdn.sozdai.ai/music/1782583687607-75e9dd8e8b89.mp3",
      "imageUrl": "https://cdn.sozdai.ai/music/cover/1782583641794-896ad6ebb572.jpeg"
    },
    {
      "id": "cmus7qam2000308l3k7m4ijkl",
      "title": "Paper Sunburn",
      "tags": "pop, upbeat, bright synth, punchy",
      "lyrics": "[Verse 1]\nCity lights on the dashboard glow\n...",
      "duration": 176.88,
      "streamUrl": "https://api.sozdai.ai/v1/media/stream/cmus7qam2000308l3k7m4ijkl/<token>",
      "audioUrl": "https://cdn.sozdai.ai/music/1782583693241-bfbcad7cf9d8.mp3",
      "imageUrl": "https://cdn.sozdai.ai/music/cover/1782583648301-bec46f245a73.jpeg"
    }
  ],
  "cost": "0.1200",
  "currency": "USD"
}

Response fields

Field	Type	Description
`status`	string	Task status: queued / submitted / succeeded / failed / timeout.
`type`	string	Media type: image / video / music.
`model`	string	The model you requested.
`tracks`	array	Generated tracks (usually 2). Each track object has the fields below.
`error`	string	Error message, present when the task failed.
`cost`	string	Amount charged for this task — a USD string (e.g. "0.1200"). See the currency field.
`currency`	string	Currency of cost — always "USD".

Track object

Field	Type	Description
`id`	string	Track id (used in streamUrl).
`title`	string	Track title.
`tags`	string	Style tags, comma-separated.
`lyrics`	string	Lyrics; "[Instrumental]" for instrumental tracks.
`duration`	number	Duration in seconds.
`streamUrl`	string	Play immediately while generating; redirects to the CDN file once stored.
`audioUrl`	string	Final mp3 on our CDN (present once ready).
`imageUrl`	string	Cover image on our CDN.

Listen while it generates

Tracks (with streamUrl, cover and lyrics) appear ~20–30s in, before the full song is ready — poll the task and start playing streamUrl right away. audioUrl (the final mp3 on our CDN) fills in when generation completes.