Suno v5 music generation. A single model, suno-v5, auto-routes to a dozen modes by which fields you send: inspiration / custom / instrumental, extend, cover, infill, underpainting, overpainting, remaster, hum-to-song, concat, persona, and sound effects. Async: create returns a taskId → poll; each run yields 2 variants.
Authorization: Bearer YOUR_API_KEY
POST https://apimodels.app/api/v1/audio/generations # create (all song modes)
GET https://apimodels.app/api/v1/audio/generations?task_id=… # poll status → resultUrls + clipIds
POST https://apimodels.app/api/v1/audio/lyrics # generate lyrics (sync text, free)Every mode uses model: "suno-v5". The mode is auto-detected from the fields you send (see table).
# ── Inspiration (一句描述，模型自动写词谱曲) ──
curl -X POST https://apimodels.app/api/v1/audio/generations \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "suno-v5", "description": "an upbeat synthwave track about a night drive", "mv": "chirp-v5" }'
# ── Custom (自带歌词 + 风格 + 标题) ──
curl -X POST https://apimodels.app/api/v1/audio/generations \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "suno-v5", "lyrics": "[Verse]\n...", "tags": "pop, female voice", "title": "Night" }'
# Poll → data.resultUrls (2 mp3s) + data.resultJson (JSON string: parse for clipIds/titles/…)
curl "https://apimodels.app/api/v1/audio/generations?task_id=TASK_ID" -H "Authorization: Bearer YOUR_API_KEY"| Field | Required | Type | Description |
|---|---|---|---|
| mv value | Suno version | Notas | |
| chirp-v5 | Suno v5 | default — latest / best | |
| chirp-v5-5 | Suno v5.5 | v5 minor iteration | |
| chirp-v4-5 | Suno v4.5 | longer songs, wide genres | |
| chirp-v4 | Suno v4 | legacy |
Omit mv to default to chirp-v5. Persona modes use tau versions internally.
| Field | Required | Type | Description |
|---|---|---|---|
| Mode | Trigger field(s) | What it does | |
| inspiration | description | one-line idea → model writes lyrics + music | |
| custom | lyrics (+ tags / title) | your own lyrics | |
| instrumental | instrumental: true | add to any mode → no vocals | |
| extend | continue_clip_id (+ continue_at) | continue from a second | |
| cover | cover_clip_id (+ lyrics) | new lyrics/style over a clip | |
| infill | infill_clip_id + infill_start_s/end_s | replace a time range only | |
| underpainting | underpainting_clip_id + start/end_s | add backing to a vocal (no lyrics) | |
| overpainting | overpainting_clip_id + start/end_s + lyrics | add vocals to instrumental | |
| remaster | remaster_clip_id (+ variation_category) | remaster whole clip (needs a prompt) | |
| hum-to-song | chop_sample_clip_id + start/end_s | hummed sample → full song | |
| concat | concat_clip_id | stitch an EXTENDED clip into one song | |
| create persona | root_clip_id + vocal_start_s/end_s | build a persona_id from a vocal segment (free) | |
| use persona | persona_id + artist_clip_id | reuse a built voice persona | |
| sound effect | sound (+ sound_type) | a short sound effect (cheaper) |
extend / cover / infill / underpainting / overpainting / remaster / hum-to-song / concat all operate on an existing clip. The clipId comes from a completed generation's data.resultJson (a JSON string — parse it and read .clipIds[]); it is the UUID in the mp3 URL, not the numeric id.
# 每个"编辑类"模式由它专属的 *_clip_id 字段自动识别；clipId = JSON.parse(data.resultJson).clipIds[]
# 哼唱成曲 — 把一段哼唱/清唱采样变成完整歌曲
curl -X POST https://apimodels.app/api/v1/audio/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "model":"suno-v5", "chop_sample_clip_id":"<clipId>", "chop_sample_start_s":0, "chop_sample_end_s":30,
"lyrics":"[Verse 1]\n...", "tags":"pop, female voice", "title":"hum to song" }'
# 局部编辑 — 只替换 [start,end] 秒区间的歌词/旋律
curl -X POST https://apimodels.app/api/v1/audio/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "model":"suno-v5", "infill_clip_id":"<clipId>", "infill_start_s":10, "infill_end_s":20, "lyrics":"[Verse]\n新片段", "tags":"pop" }'
# 加人声 — 给纯音乐加演唱人声（overpainting_clip_id + 歌词）
# 加伴奏 — 给清唱配伴奏（underpainting_clip_id，无需歌词）
# 重制 — 整体重制（remaster_clip_id + variation_category: low|medium|high）
# 续写 — continue_clip_id + continue_at；翻唱 — cover_clip_idA separate synchronous endpoint that returns lyric text directly (not a task). Paste the result into the lyrics field of a song request. Free for authenticated keys.
# 生成歌词（同步返回文本，免费；把结果填进上面的 lyrics 字段即可）
curl -X POST https://apimodels.app/api/v1/audio/lyrics -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "prompt": "my love" }'
# → { "code":200, "data": { "lyric": "[Verse 1]\n...", "title": "...", "tags": "..." } }| Field | Required | Type | Description |
|---|---|---|---|
| Field | Type | Description | |
| model | string | always "suno-v5" | |
| mv | string | model version, default chirp-v5 | |
| description | string | inspiration: one-line idea | |
| lyrics | string | lyrics, supports [Verse]/[Chorus], up to 3000 chars | |
| tags | string | style, e.g. "pop, female voice", up to 200 chars | |
| title | string | title | |
| instrumental | boolean | instrumental only (no vocals) | |
| *_clip_id / *_start_s / *_end_s | string / number | target clip + time range for edit modes (see table) | |
| variation_category | string | remaster strength: low / medium / high | |
| callback_url | string | webhook on completion (optional) |
| Field | Required | Type | Description |
|---|---|---|---|
| Field | Type | Description | |
| code | integer | 200 on success; otherwise an error code | |
| data.taskId | string | task id for polling | |
| data.state | string | pending / processing / completed / failed | |
| data.resultUrls | string[] | the 2 finished mp3 R2 URLs (when completed) | |
| data.resultJson | string (JSON) | JSON string; parse for clipIds[], titles[], durations[], coverUrls[], tags, lyrics. clipIds feed the edit modes | |
| data.credits | number | amount charged ($), on success only | |
| data.costTime | integer | duration (ms) | |
| data.failMsg | string | failure reason (when state=failed) |
| Field | Required | Type | Description |
|---|---|---|---|
| Type | Price | ||
| Song generation (all modes) | $0.26 / call (2 songs) | ||
| sound effect | $0.05 | ||
| create persona / generate lyrics | free |
Charged on success only; failures are free.
See also: Other audio APIs (ElevenLabs / Kling)
Song generation is $0.26 per request (returns 2 variants); sound effects $0.05; creating a persona and generating lyrics are free. Charged only on success.
Yes — the hum-to-song mode. Generate or upload a clip, then pass chop_sample_clip_id + a time range + lyrics; Suno turns the sample into a full arranged song.
Inspiration, custom lyrics, instrumental, extend, cover, infill (partial edit), add-backing, add-vocals, remaster, hum-to-song, concat, persona and sound effects — all via model suno-v5, mode auto-detected from fields.