Docs/Música/Texto para imagem

Suno Music· Texto para imagem

Texto para imagem

POSThttps://api.foxwire.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.

#Submeter uma tarefa

A geração de multimédia é assíncrona: obtém imediatamente um id de tarefa, sem esperar.

bash

curl https://api.foxwire.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" }

#Parâmetros do pedido

Parâmetro	Tipo	Obrigatório	Predefinição	Descrição
`version`	string	Não	`V5_5`	Suno engine version (the model is a parameter, not a separate endpoint). Default V5_5 (latest). Opções: V5_5, V5, V4_5PLUS, V4_5, V4_5ALL, V4
`prompt`	string	Sim	—	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	Não	`false`	Advanced control. When true, style+title required (and prompt as lyrics unless instrumental).
`instrumental`	boolean	Não	`false`	Generate instrumental (no vocals).
`style`	string	Não	—	Genre/mood (required in custom mode). Max 200 chars on V4, 1000 on every other version. e.g. Synthwave, Jazz, Lo-fi.
`title`	string	Não	—	Track title (required in custom mode, max 80 chars).
`negativeTags`	string	Não	—	Styles/traits to avoid. e.g. Heavy Metal.
`vocalGender`	string	Não	—	Preferred vocal gender (custom mode only; best-effort). Opções: m, f
`styleWeight`	number	Não	—	How strongly to follow the style. Range 0–1, up to 2 decimals.
`weirdnessConstraint`	number	Não	—	Experimental/creative deviation. Range 0–1, up to 2 decimals.
`audioWeight`	number	Não	—	Balance weight for audio features vs. other factors. Range 0–1, up to 2 decimals.
`personaId`	string	Não	—	Apply a Persona/Voice to the generation. Custom mode only.
`personaModel`	string	Não	—	Persona type. Only available on V5 and V5_5. Opções: style_persona, voice_persona
`callback_url`	string	Não	—	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.foxwire.ai/v1/media/generations/{id}

bash

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

#Exemplo de resposta

Na submissão

json

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

Em caso de sucesso (após consulta)

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.foxwire.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.foxwire.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"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	string	Estado da tarefa: queued / submitted / succeeded / failed / timeout.
`type`	string	Tipo de multimédia: image / video / music.
`model`	string	O modelo que solicitou.
`tracks`	array	Generated tracks (usually 2). Each track object has the fields below.
`error`	string	Mensagem de erro, presente quando a tarefa falhou.
`cost`	string	Montante cobrado por esta tarefa — uma string em USD (ex.: "0.1200"). Consulte o campo currency.
`currency`	string	Currency of cost — always "USD".

Track object

Campo	Tipo	Descrição
`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.