APIMODELSAPIMODELS
Документация API

apimodels.app

Suno Music API

Suno music generation (v5 / v6 — pick the version with mv). 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.

Auth & Endpoints

Authorization: Bearer YOUR_API_KEY

POST https://api.apimodels.app/v1/audio/generations        # create (all song modes)
GET  https://api.apimodels.app/v1/audio/generations?task_id=…   # poll status → resultUrls + clipIds
POST https://api.apimodels.app/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).

Basic Generation

# ── Inspiration (一句描述,模型自动写词谱曲) ──
curl -X POST https://api.apimodels.app/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://api.apimodels.app/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://api.apimodels.app/v1/audio/generations?task_id=TASK_ID" -H "Authorization: Bearer YOUR_API_KEY"

Model version (mv)

FieldRequiredTypeDescription
mv valueSuno versionNotes
chirp-v5Suno v5default (used when mv is omitted)
chirp-v6Suno v6Suno's newest generation (released September 2026), same price as v5
chirp-v5-5Suno v5.5v5 minor iteration
chirp-v4-5Suno v4.5longer songs, wide genres
chirp-v4Suno v4legacy

Omit mv to default to chirp-v5; for v6 send "mv": "chirp-v6" explicitly — the model name stays suno-v5. Persona modes use tau versions internally.

All modes (auto-detected by trigger fields)

FieldRequiredTypeDescription
ModeTrigger field(s)What it does
inspirationdescriptionone-line idea → model writes lyrics + music
customlyrics (+ tags / title)your own lyrics
instrumentalinstrumental: trueadd to any mode → no vocals
extendcontinue_clip_id (+ continue_at)continue from a second
covercover_clip_id (+ lyrics)new lyrics/style over a clip
infillinfill_clip_id + infill_start_s/end_sreplace a time range only
underpaintingunderpainting_clip_id + start/end_sadd backing to a vocal (no lyrics)
overpaintingoverpainting_clip_id + start/end_s + lyricsadd vocals to instrumental
remasterremaster_clip_id (+ variation_category)remaster whole clip (needs a prompt)
hum-to-songchop_sample_clip_id + start/end_shummed sample → full song
concatconcat_clip_idstitch an EXTENDED clip into one song
create personaroot_clip_id + vocal_start_s/end_sbuild a persona_id from a vocal segment (free)
use personapersona_id + artist_clip_idreuse a built voice persona
sound effectsound (+ sound_type)a short sound effect (more affordable)

Edit modes (need a clipId)

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://api.apimodels.app/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://api.apimodels.app/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_id

Generate lyrics (free, sync)

A 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://api.apimodels.app/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": "..." } }

Common Parameters

FieldRequiredTypeDescription
FieldTypeDescription
modelstringalways "suno-v5"
mvstringmodel version, default chirp-v5; chirp-v6 selects Suno v6
descriptionstringinspiration: one-line idea
lyricsstringlyrics, supports [Verse]/[Chorus], up to 3000 chars
tagsstringstyle, e.g. "pop, female voice", up to 200 chars
titlestringtitle
instrumentalbooleaninstrumental only (no vocals)
*_clip_id / *_start_s / *_end_sstring / numbertarget clip + time range for edit modes (see table)
variation_categorystringremaster strength: low / medium / high
callback_urlstringwebhook on completion (optional)

Response Fields

FieldRequiredTypeDescription
FieldTypeDescription
codeinteger200 on success; otherwise an error code
data.taskIdstringtask id for polling
data.statestringpending / processing / completed / failed
data.resultUrlsstring[]the 2 finished mp3 R2 URLs (when completed)
data.resultJsonstring (JSON)JSON string; parse for clipIds[], titles[], durations[], coverUrls[], tags, lyrics. clipIds feed the edit modes
data.creditsnumberamount charged ($), on success only
data.costTimeintegerduration (ms)
data.failMsgstringfailure reason (when state=failed)

Notes

  • Async: POST returns a taskId; poll GET ?task_id= until state=completed. Each run makes 2 variants.
  • Finished mp3s are in data.resultUrls; clipIds / covers / titles / durations live inside data.resultJson (a JSON string — parse it). See the response-fields table above.
  • Result files are stored on R2 and auto-deleted after 30 days — download or re-host promptly.
  • remaster requires a lyric/prompt upstream (otherwise it errors with "Need prompt").
  • concat only accepts a clip produced by an extend; a normal clip errors with "not a continuation".
  • Creating a persona is free ($0) and returns persona_id + artist_clip_id; reuse it via the persona mode.

Pricing

FieldRequiredTypeDescription
TypePrice
Song generation (all modes)$0.26 / call (2 songs)
sound effect$0.05
create persona / generate lyricsfree

Charged on success only; failures are free.

See also: Other audio APIs (ElevenLabs / Kling)

FAQ

How much does the Suno music API cost?

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.

Can Suno turn a hummed melody into a full song?

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.

What Suno modes are supported?

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.