문서/음악/텍스트 → 이미지

Suno Music· 텍스트 → 이미지

텍스트 → 이미지

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.

#작업 제출

미디어 생성은 비동기입니다. 기다리지 않고 즉시 작업 id를 받습니다.

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

#요청 매개변수

매개변수	유형	필수	기본값	설명
`version`	string	아니요	`V5_5`	Suno engine version (the model is a parameter, not a separate endpoint). Default V5_5 (latest). 옵션: V5_5, V5, V4_5PLUS, V4_5, V4_5ALL, V4
`prompt`	string	예	—	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	아니요	`false`	Advanced control. When true, style+title required (and prompt as lyrics unless instrumental).
`instrumental`	boolean	아니요	`false`	Generate instrumental (no vocals).
`style`	string	아니요	—	Genre/mood (required in custom mode). Max 200 chars on V4, 1000 on every other version. e.g. Synthwave, Jazz, Lo-fi.
`title`	string	아니요	—	Track title (required in custom mode, max 80 chars).
`negativeTags`	string	아니요	—	Styles/traits to avoid. e.g. Heavy Metal.
`vocalGender`	string	아니요	—	Preferred vocal gender (custom mode only; best-effort). 옵션: m, f
`styleWeight`	number	아니요	—	How strongly to follow the style. Range 0–1, up to 2 decimals.
`weirdnessConstraint`	number	아니요	—	Experimental/creative deviation. Range 0–1, up to 2 decimals.
`audioWeight`	number	아니요	—	Balance weight for audio features vs. other factors. Range 0–1, up to 2 decimals.
`personaId`	string	아니요	—	Apply a Persona/Voice to the generation. Custom mode only.
`personaModel`	string	아니요	—	Persona type. Only available on V5 and V5_5. 옵션: style_persona, voice_persona
`callback_url`	string	아니요	—	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")

#응답 예시

제출 시

json

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

성공 시(폴링 후)

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

응답 필드

필드	유형	설명
`status`	string	작업 상태: queued / submitted / succeeded / failed / timeout.
`type`	string	미디어 유형: image / video / music.
`model`	string	요청한 모델.
`tracks`	array	Generated tracks (usually 2). Each track object has the fields below.
`error`	string	오류 메시지. 작업이 실패했을 때 존재합니다.
`cost`	string	이 작업에 청구된 금액 — USD 문자열(예: "0.1200"). currency 필드를 참고하세요.
`currency`	string	Currency of cost — always "USD".

Track object

필드	유형	설명
`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.