GlobalAiOpcGlobalAiOpc
微信微信
登录
Model CenterGlobalAiOpc

Suno音乐生成

POST/kyyReactApiServer/v2/model-center/tasks

价格

登录后查看当前账号的价格及可用规格。请使用页面顶部的登录入口。
使用 Suno 将音乐灵感或自写歌词变成歌曲。支持灵感模式（用一句话描述想要的音乐）、自定义模式（填写歌词、风格和歌名），也可以生成无人声的纯音乐。
每次请求生成 2 首，每首歌曲返回一个任务 ID。提交后逐个查询，即可获取音频、封面等生成结果。

快速开始

  1. 将下方示例中的 <API_KEY> 替换为你的 API 密钥，修改创作内容后提交请求。
  2. 保存响应中的 task_ids，逐个查询，每隔 3–5 秒查询一次即可。
  3. 当 status 为 completed 时，使用返回的文件链接获取作品。

请求地址

http
POST https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks

认证

获取 Key
所有请求都需要 API 密钥。提交时使用以下请求头，将 <API_KEY> 替换为你的密钥。
http
Authorization: Bearer <API_KEY>
Content-Type: application/json

选择创作方式

灵感模式

没有歌词也能创作。用 gpt_description_prompt 描述主题、曲风、情绪和演唱语言。

自定义歌词

已有歌词，按指定曲风演唱。同时填写 prompt（歌词）、tags（风格）和 title（歌名）。
制作无人声配乐：填写 gpt_description_prompt 描述音乐，并设置 make_instrumental 为 true。
每种方式都需要填写 model 和 mv。gpt_description_prompt 与 prompt 不要同时填写。首次调用可直接复制下方“灵感模式”示例。

请求参数

以下参数放在请求体（JSON）中提交。标记“必填”的参数每次都要提供，其余参数按所选创作方式填写。
modelstring必填
模型名称
填写此模型名称。
取值与限制：suno_music
mvstring必填
音乐版本
音乐版本，见下方版本说明。
取值与限制：可选值："chirp-hawk"；"chirp-hawk-wild"；"chirp-goose"
gpt_description_promptstring
音乐灵感描述
描述生成时必填
灵感模式的音乐描述，例如“一首欢快的中文流行歌，讲述夏日旅行”；无需准备歌词。不要同时填写 prompt。
取值与限制：至少 1 个字符
promptstring
自定义歌词
自定义歌词时必填
自定义模式的歌词正文，可用 [Verse] 标记主歌、[Chorus] 标记副歌；换行使用 \n。不要同时填写 gpt_description_prompt。
取值与限制：至少 1 个字符; 最多 3000 个字符
tagsstring
音乐风格
自定义歌词时必填
自定义模式的音乐风格，例如 pop, acoustic, warm；可组合流派、乐器和情绪。
取值与限制：至少 1 个字符; 最多 200 个字符
titlestring
歌曲名称
自定义歌词时必填
歌曲名称；自定义模式必填。
取值与限制：至少 1 个字符; 最多 80 个字符
make_instrumentalboolean
纯音乐
是否生成无人声的纯音乐：true 为纯音乐，false 为歌曲。
negative_tagsstring
排除风格
不希望出现的风格或元素，例如 heavy metal, drums；没有排除要求时可省略。

高级选项（可选）

首次调用可省略 metadata。需要指定人声或调整创作效果时，再填写其中的选项。

音乐版本

model 使用本页的模型名称，mv 从下表选择音乐版本。例如，使用 V6 时填写 "mv": "chirp-hawk"。
mv 的值音乐版本特点与适用场景
chirp-hawkV6稳定精准，适合高质量成品创作。
chirp-hawk-wildV6-wild更具创意与随机性，适合探索灵感。
chirp-gooseV6-mini快速高效，适合轻量创作。

请求示例

选择创作方式查看请求内容。右侧提供 cURL、Python、JavaScript 完整调用代码；Python 示例需先安装 requests，JavaScript 示例可使用 Node.js 18+。
JSON
{
  "model": "suno_music",
  "mv": "chirp-hawk",
  "gpt_description_prompt": "一首温暖的普通话民谣，木吉他与轻柔女声，讲述夏日重逢。"
}

提交响应

请求成功返回 HTTP 202，表示已开始排队。作品生成需要时间，请继续查询任务。
字段说明
task_ids本次生成的全部任务 ID。请保存并逐个查询，避免遗漏作品。
id第一个任务的 ID。
statusqueued 表示排队中。
error错误信息；无错误时为 null。

查询结果

http
GET https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks/{task_id}
task_idstring必填
将地址中的 {task_id} 替换为提交响应 task_ids 中的一个值，并使用同一个 API 密钥查询。每个任务分别查询，保存并使用全部任务 ID。

任务状态

status含义下一步
queued排队中等待 3–5 秒后再次查询。
processing处理中（生成或文件交付）等待 3–5 秒后再次查询。
completed已完成读取返回的业务字段，使用媒体地址播放或下载。
failed生成失败查看 error 了解原因；退款进度见 refund_status。
delivery_exception作品生成成功，但文件暂时无法获取停止轮询，联系支持处理；不要重复提交。
manual_required任务需要人工核查停止轮询，保留任务 ID 并联系支持；不要重复提交。

完成响应示例

JSON
{
  "id": "mcp_00000000000000000000000000000001",
  "model": "suno_music",
  "object": "audio",
  "created": 1792022400,
  "status": "completed",
  "amount": 0.25,
  "billing_status": "deducted",
  "refund_status": "none",
  "music_id": "示例文本",
  "prompt": "示例文本",
  "title": "示例文本",
  "audio_url": "https://storage.example.com/audio.bin",
  "cover_image_url": "https://storage.example.com/cover_image.bin",
  "error": null
}
示例地址和积分仅作说明。实际费用以账户配置及任务记录为准；只有 completed 状态才可获取生成文件。

返回字段

字段说明
id当前查询的任务 ID。
model使用的模型名称。
object结果类型，例如 audio、video。
created任务创建时间，Unix 时间戳，单位为秒。
status任务状态，completed 表示完成。
amount / billing_status / refund_status该任务消耗的积分、扣费状态和退款状态。
error错误信息；成功时为 null。
error_code发生错误时返回的平台错误代码。
媒体地址字段说明
audio_url音频下载地址；完成时返回
cover_image_url图片 / 封面地址；可选，没有文件时省略

结果字段

字段类型必返说明
music_idstring否歌曲id
promptstring否歌词
titlestring否歌曲名称
返回的媒体地址均为平台保存后的地址，可直接用于播放或下载。可选文件未交付时不返回对应地址。

费用与常见问题

每首歌曲单独计费。一次生成多首时，总费用为每首价格之和；其中一首生成失败，只退该首费用，其他成功歌曲仍可正常使用。实际价格以账号显示为准。
  • 提交超时：请先确认原请求是否成功，避免重复生成和扣费；已有任务 ID 时直接查询该任务。
  • 查询暂时失败：稍后使用原任务 ID 重试查询，不需要重新生成。
  • 返回 delivery_exception：生成费用保留，请联系支持恢复文件。