文档 / 音乐系列 / Suno / 音乐生成

音乐生成POSTSunoMUSICAsync Taskssuno_music

[核心]音乐生成

通过统一音乐生成接口提交异步任务，并使用公开任务 ID 查询规范化音乐结果。

POSThttps://api.apimax.ai/v1/music/generations

试一试

Bearer API KeyJSON服务端调用

用途#

通过 POST /v1/music/generations 创建音乐生成任务。接口会立即返回任务 ID，可通过任务查询接口获取进度和最终音频。

请求字段#

字段	类型	必填	说明
`model`	string	否	使用的音乐模型,默认 `suno_music`;可用版本 `chirp-v6`、`chirp-v6-wild`、`chirp-v6-mini`,直接传版本名即可,也兼容 `suno/<version>` 形式
`prompt`	string	条件必填	未传 `lyrics` 且 `instrumental=false` 时必填;纯伴奏可省略。简单模式描述,≤3000 字符
`lyrics`	string	条件必填	自定义歌词;传入后即按自定义歌词模式处理,无需 `prompt`。≤5000 字符
`instrumental`	boolean	否	是否生成纯音乐，默认 `false`；兼容旧字段 `make_instrumental`
`title`	string	自定义歌词时必填	歌曲标题,≤100 字符
`style`	string	自定义歌词时必填	曲风、速度、人声和制作描述,≤1000 字符
`negative_tags`	string	否	不希望出现的风格或特征,≤1000 字符
`duration`	integer	否	自定义时长(秒),10–360 整数;不传为自动。上游按模型解释,较新模型生效、旧模型可能忽略
`persona_id`	string	否	已创建的人声音色 ID
`callback_url`	string	否	任务完成或失败时接收通知的 HTTPS 地址
`model_params`	object	否	附加参数,原样作为上游 `metadata` 透传;常用键:`vocal_gender`(`m`/`f`)、`control_sliders`(创作滑杆)、`is_max_mode`(Max 模式)等。`mv`、`persona_id`、`task` 等提交顶层字段不允许在此夹带

有声请求提供非空 prompt（普通模式）或 lyrics 并填写 title 和 style（自定义歌词模式，传入 lyrics 即生效）；纯伴奏请求可省略 prompt 与歌词。

长度上限为 chirp-v6 家族官方确认值(描述 3000 / 自定义歌词 5000 / 标题 100 / 风格 1000 / 反向标签 1000);旧版本模型家族上限更低(如 v3 系为 3000/200),超限会被上游拒绝。

model_params 子字段#

model_params 整个对象会原样作为上游 metadata 透传,除下表列出的常用键外,上游后续新增的 metadata 键也直接传即可:

子字段	类型	说明
`vocal_gender`	string	人声性别:`m`(男)/ `f`(女)
`control_sliders`	object	创作滑杆,子键 `weirdness_constraint`(怪异度)/ `style_weight`(风格权重)/ `audio_weight`(音频权重),取值 0–1
`infill_lyrics`	string	段落替换(infill)的替换段歌词,仅段落替换动作接口使用
`is_max_mode`	boolean	Max 模式开关(v6 家族的更高音质档),仅自定义歌词模式(传入 `lyrics`)下生效;开启后按双倍计费

注意:mv、persona_id、task、continue_clip_id 等属于提交顶层字段,不允许夹带在 model_params 里(会被拒绝并提示改用顶层字段)。

请求示例#

最简生成(默认模型,仅 prompt):

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6",
    "prompt": "A summer road-trip anthem with warm vocals"
  }'

自定义歌词与元信息(传入 lyrics 即自定义歌词模式):

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6",
    "lyrics": "[Verse] Driving down the open road\n[Chorus] Chasing the summer light",
    "title": "Summer Dream",
    "style": "pop, electronic, upbeat, female vocals",
    "instrumental": false,
    "callback_url": "https://your-app.example/music-callback"
  }'

指定 chirp-v6-wild 版本并排除不想要的风格:

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6-wild",
    "prompt": "energetic rock with gritty guitars",
    "negative_tags": "distortion, heavy drums",
    "callback_url": "https://your-app.example/music-callback"
  }'

纯音乐(无需歌词,各版本价格相同,以 chirp-v6-mini 为例):

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6-mini",
    "prompt": "lofi study beat, warm piano, soft rain",
    "instrumental": true
  }'

使用人声音色翻唱式生成:

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6",
    "persona_id": "7d20fabc-1a2b-4c3d-8e9f-0123456789ab",
    "lyrics": "[Verse] We kept our names inside an old notebook\n[Chorus] Those summer days still call me home",
    "title": "Old School Days",
    "style": "acoustic pop, warm female vocal"
  }'

通过 model_params 指定人声性别:

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6",
    "prompt": "an upbeat summer anthem",
    "model_params": {
      "vocal_gender": "f"
    }
  }'

自定义歌词 + 人声性别组合:

bash

curl -X POST 'https://api.apimax.ai/v1/music/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v6",
    "lyrics": "[Verse] City lights are calling\n[Chorus] We run through the neon glow",
    "title": "Neon Run",
    "style": "synthwave, energetic",
    "model_params": {
      "vocal_gender": "m"
    }
  }'

callback_url 应由你的服务端接收并快速返回 2xx。不要将需要登录的页面地址作为回调地址。

提交响应#

提交成功后会立即返回任务 ID：

json

{
  "code": "success",
  "message": "",
  "data": "task_01KABCDEF0123456789XYZ"
}

字段	类型	说明
`code`	string	成功时固定为 `success`
`message`	string	成功时通常为空字符串
`data`	string	用于查询结果的任务 ID

查询任务结果#

仅支持按任务 ID 查询单个任务：

bash

curl 'https://api.apimax.ai/v1/tasks/task_01KABCDEF0123456789XYZ' \
  -H "Authorization: Bearer $API_KEY"

任务状态按以下顺序流转：

queued → in_progress → completed / failed

`status`	说明	是否终态
`queued`	任务已创建，等待处理	否
`in_progress`	任务正在处理	否
`completed`	任务处理完成，结果位于 `data`	是
`failed`	任务处理失败，原因位于 `error`	是

建议每 2~5 秒查询一次。进入 completed 或 failed 后停止查询。设置了 callback_url 时，也可以等待回调通知。

完成响应示例（两个候选）：

json

{
  "id": "task_3FMX35Pz3RRzBoka1hl6U9dIpxto8L6u",
  "object": "task",
  "type": "music",
  "platform": "music",
  "status": "completed",
  "progress": 100,
  "model": "suno_music",
  "created_at": 1791338149,
  "started_at": 1791338180,
  "finished_at": 1791338240,
  "data": [
    {
      "id": "85586e7d-0dbc-4a82-9115-028f8e1ab142",
      "audio_url": "https://media.example/cdn/85586e7d-0dbc-4a82-9115-028f8e1ab142.m4a",
      "image_url": "https://media.example/image_85586e7d-0dbc-4a82-9115-028f8e1ab142.jpeg",
      "title": "沿着弯弯的路",
      "duration": 182.08,
      "status": "complete",
      "model_name": "suno_music",
      "provider": "suno",
      "created_at": "2026-10-07T01:55:50.317Z",
      "metadata": {
        "duration": 182.08,
        "gpt_description_prompt": "去旅行",
        "prompt": "[Verse 1]\n把旧地图摊在早餐店的桌上\n……（完整歌词此处省略）",
        "tags": "Mandarin indie pop with a breezy road-trip groove, bright acoustic guitar strums, warm electric bass, crisp live drums"
      }
    },
    {
      "id": "b617832e-2438-4584-826d-9ea6bd7116fd",
      "audio_url": "https://media.example/cdn/b617832e-2438-4584-826d-9ea6bd7116fd.m4a",
      "image_url": "https://media.example/image_b617832e-2438-4584-826d-9ea6bd7116fd.jpeg",
      "title": "沿着弯弯的路",
      "duration": 211.56,
      "status": "complete",
      "model_name": "suno_music",
      "provider": "suno",
      "created_at": "2026-10-07T01:55:50.317Z",
      "metadata": {
        "duration": 211.56,
        "gpt_description_prompt": "去旅行",
        "prompt": "[Verse 1]\n把旧地图摊在早餐店的桌上\n……（完整歌词此处省略）",
        "tags": "Mandarin indie pop with a breezy road-trip groove, bright acoustic guitar strums, warm electric bass, crisp live drums"
      }
    }
  ]
}

in_progress 中间态示例（progress 尚未到 100 时，歌词等元数据可能已经生成，但 audio_url 还是占位地址，不可下载；继续轮询到终态再取媒体地址）：

json

{
  "id": "task_3FMX35Pz3RRzBoka1hl6U9dIpxto8L6u",
  "object": "task",
  "type": "music",
  "platform": "music",
  "status": "in_progress",
  "progress": 50,
  "model": "suno_music",
  "created_at": 1791338149,
  "started_at": 1791338180,
  "data": [
    {
      "id": "85586e7d-0dbc-4a82-9115-028f8e1ab142",
      "audio_url": "https://studio-api.prod.suno.com/api/forbidden",
      "image_url": "https://media.example/image_85586e7d-0dbc-4a82-9115-028f8e1ab142.jpeg",
      "title": "沿着弯弯的路",
      "duration": 182.08,
      "status": "complete",
      "model_name": "suno_music",
      "provider": "suno",
      "created_at": "2026-10-07T01:55:50.317Z",
      "metadata": { "duration": 182.08, "gpt_description_prompt": "去旅行", "prompt": "……（歌词已生成，此处省略）", "tags": "Mandarin indie pop" }
    },
    {
      "id": "b617832e-2438-4584-826d-9ea6bd7116fd",
      "audio_url": "https://studio-api.prod.suno.com/api/forbidden",
      "image_url": "https://media.example/image_b617832e-2438-4584-826d-9ea6bd7116fd.jpeg",
      "title": "沿着弯弯的路",
      "duration": 211.56,
      "status": "complete",
      "model_name": "suno_music",
      "provider": "suno",
      "created_at": "2026-10-07T01:55:50.317Z",
      "metadata": { "duration": 211.56, "gpt_description_prompt": "去旅行", "prompt": "……（歌词已生成，此处省略）", "tags": "Mandarin indie pop" }
    }
  ]
}

in_progress 阶段可能提前返回可预览音频，但仍应继续查询至终态。

字段

类型

必填

说明

model

string

否

使用的音乐模型,默认 suno_music;可用版本 chirp-v6、chirp-v6-wild、chirp-v6-mini,直接传版本名即可,也兼容 suno/<version> 形式

prompt

string

条件必填

未传 lyrics 且 instrumental=false 时必填;纯伴奏可省略。简单模式描述,≤3000 字符

lyrics

string

条件必填

自定义歌词;传入后即按自定义歌词模式处理,无需 prompt。≤5000 字符

instrumental

boolean

否

是否生成纯音乐，默认 false；兼容旧字段 make_instrumental

title

string

自定义歌词时必填

歌曲标题,≤100 字符

style

string

自定义歌词时必填

曲风、速度、人声和制作描述,≤1000 字符

negative_tags

string

否

不希望出现的风格或特征,≤1000 字符

duration

integer

否

自定义时长(秒),10–360 整数;不传为自动。上游按模型解释,较新模型生效、旧模型可能忽略

persona_id

string

否

已创建的人声音色 ID

callback_url

string

否

任务完成或失败时接收通知的 HTTPS 地址

model_params

object

否

附加参数,原样作为上游 metadata 透传;常用键:vocal_gender(m/f)、control_sliders(创作滑杆)、is_max_mode(Max 模式)等。mv、persona_id、task 等提交顶层字段不允许在此夹带

子字段

类型

说明

vocal_gender

string

人声性别:m(男)/ f(女)

control_sliders

object

创作滑杆,子键 weirdness_constraint(怪异度)/ style_weight(风格权重)/ audio_weight(音频权重),取值 0–1

infill_lyrics

string

段落替换(infill)的替换段歌词,仅段落替换动作接口使用

is_max_mode

boolean

Max 模式开关(v6 家族的更高音质档),仅自定义歌词模式(传入 lyrics)下生效;开启后按双倍计费

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6", "prompt": "A summer road-trip anthem with warm vocals" }'

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6", "lyrics": "[Verse] Driving down the open road\n[Chorus] Chasing the summer light", "title": "Summer Dream", "style": "pop, electronic, upbeat, female vocals", "instrumental": false, "callback_url": "https://your-app.example/music-callback" }'

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6-wild", "prompt": "energetic rock with gritty guitars", "negative_tags": "distortion, heavy drums", "callback_url": "https://your-app.example/music-callback" }'

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6-mini", "prompt": "lofi study beat, warm piano, soft rain", "instrumental": true }'

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6", "persona_id": "7d20fabc-1a2b-4c3d-8e9f-0123456789ab", "lyrics": "[Verse] We kept our names inside an old notebook\n[Chorus] Those summer days still call me home", "title": "Old School Days", "style": "acoustic pop, warm female vocal" }'

curl -X POST 'https://api.apimax.ai/v1/music/generations' \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "chirp-v6", "lyrics": "[Verse] City lights are calling\n[Chorus] We run through the neon glow", "title": "Neon Run", "style": "synthwave, energetic", "model_params": { "vocal_gender": "m" } }'

字段

类型

说明

code

string

成功时固定为 success

message

string

成功时通常为空字符串

data

string

用于查询结果的任务 ID

status

说明

是否终态

queued

任务已创建，等待处理

否

in_progress

任务正在处理

否

completed

任务处理完成，结果位于 data

是

failed

任务处理失败，原因位于 error

是

{ "id": "task_3FMX35Pz3RRzBoka1hl6U9dIpxto8L6u", "object": "task", "type": "music", "platform": "music", "status": "completed", "progress": 100, "model": "suno_music", "created_at": 1791338149, "started_at": 1791338180, "finished_at": 1791338240, "data": [ { "id": "85586e7d-0dbc-4a82-9115-028f8e1ab142", "audio_url": "https://media.example/cdn/85586e7d-0dbc-4a82-9115-028f8e1ab142.m4a", "image_url": "https://media.example/image_85586e7d-0dbc-4a82-9115-028f8e1ab142.jpeg", "title": "沿着弯弯的路", "duration": 182.08, "status": "complete", "model_name": "suno_music", "provider": "suno", "created_at": "2026-10-07T01:55:50.317Z", "metadata": { "duration": 182.08, "gpt_description_prompt": "去旅行", "prompt": "[Verse 1]\n把旧地图摊在早餐店的桌上\n……（完整歌词此处省略）", "tags": "Mandarin indie pop with a breezy road-trip groove, bright acoustic guitar strums, warm electric bass, crisp live drums" } }, { "id": "b617832e-2438-4584-826d-9ea6bd7116fd", "audio_url": "https://media.example/cdn/b617832e-2438-4584-826d-9ea6bd7116fd.m4a", "image_url": "https://media.example/image_b617832e-2438-4584-826d-9ea6bd7116fd.jpeg", "title": "沿着弯弯的路", "duration": 211.56, "status": "complete", "model_name": "suno_music", "provider": "suno", "created_at": "2026-10-07T01:55:50.317Z", "metadata": { "duration": 211.56, "gpt_description_prompt": "去旅行", "prompt": "[Verse 1]\n把旧地图摊在早餐店的桌上\n……（完整歌词此处省略）", "tags": "Mandarin indie pop with a breezy road-trip groove, bright acoustic guitar strums, warm electric bass, crisp live drums" } } ] }

{ "id": "task_3FMX35Pz3RRzBoka1hl6U9dIpxto8L6u", "object": "task", "type": "music", "platform": "music", "status": "in_progress", "progress": 50, "model": "suno_music", "created_at": 1791338149, "started_at": 1791338180, "data": [ { "id": "85586e7d-0dbc-4a82-9115-028f8e1ab142", "audio_url": "https://studio-api.prod.suno.com/api/forbidden", "image_url": "https://media.example/image_85586e7d-0dbc-4a82-9115-028f8e1ab142.jpeg", "title": "沿着弯弯的路", "duration": 182.08, "status": "complete", "model_name": "suno_music", "provider": "suno", "created_at": "2026-10-07T01:55:50.317Z", "metadata": { "duration": 182.08, "gpt_description_prompt": "去旅行", "prompt": "……（歌词已生成，此处省略）", "tags": "Mandarin indie pop" } }, { "id": "b617832e-2438-4584-826d-9ea6bd7116fd", "audio_url": "https://studio-api.prod.suno.com/api/forbidden", "image_url": "https://media.example/image_b617832e-2438-4584-826d-9ea6bd7116fd.jpeg", "title": "沿着弯弯的路", "duration": 211.56, "status": "complete", "model_name": "suno_music", "provider": "suno", "created_at": "2026-10-07T01:55:50.317Z", "metadata": { "duration": 211.56, "gpt_description_prompt": "去旅行", "prompt": "……（歌词已生成，此处省略）", "tags": "Mandarin indie pop" } } ] }

用途#

请求字段#

model_params 子字段#

请求示例#

提交响应#

查询任务结果#

下一步

用途#

请求字段#

model_params 子字段#

请求示例#

提交响应#

查询任务结果#

下一步