跳转到主要内容

​
接口

POST /api/v1/music/generate
这是一个异步接口，立即返回 task_id。使用 获取任务 轮询结果。

​
请求参数

字段类型是否必填说明
promptstring见说明歌词内容或歌曲描述，支持中英文。未提供 tags 或 gpt_description_prompt 时必填。
titlestring否曲目标题
tagsstring见说明风格标签（如 "流行 治愈 女声" 或 "pop upbeat female vocals"）。未提供 prompt 或 gpt_description_prompt 时必填。
gpt_description_promptstring见说明灵感模式。 用自然语言描述歌曲，而非直接写歌词（如 "一首关于夏天和友情的欢快中文流行歌"）。不可与 prompt/tags 同时使用。
make_instrumentalboolean否生成纯伴奏（无人声）。默认 false。
persona_idstring否AI 歌手音色 ID。使用从特定音频片段训练的自定义音色。通过 创建 Persona 获取。
continue_clip_idstring否续写已有片段。提供要续写的 Clip ID。
continue_atinteger否续写的起始位置（秒）。仅与 continue_clip_id 配合使用。
callback_urlstring否任务完成时接收 Webhook 回调的 URL。
retention_daysinteger否音频文件保存天数。默认 7，最大 30。
prompt、tags、gpt_description_prompt 三者至少提供一个。 gpt_description_prompt 不可与 prompt 或 tags 同时使用。

​
语言支持

所有文本字段（prompt、title、tags、gpt_description_prompt）均支持中文和英文。 
{
  "prompt": "[主歌]\n风吹过树梢\n阳光洒在肩头\n[副歌]\n我在这里等你回来",
  "title": "等你回来",
  "tags": "流行 抒情 女声"
}

​
响应

{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
字段类型说明
task_idstring用于轮询 获取任务 的任务 ID
statusstring初始状态，固定为 "queuing"

​
示例

自定义模式（歌词 + 标签）： 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[主歌]\n风吹过树梢\n阳光洒在肩头\n[副歌]\n我在这里等你回来",
    "title": "等你回来",
    "tags": "流行 抒情 女声",
    "callback_url": "https://yourserver.com/webhooks/music"
  }'
灵感模式（自然语言描述）： 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt": "一首关于思念故乡的中国民谣，轻柔吉他，女声演唱"
  }'
使用自定义 AI 歌手音色： 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[主歌]\n雨夜让我想起你\n[副歌]\n请你回来吧",
    "tags": "rnb 慢歌 女声",
    "persona_id": "persona-abc123"
  }'
续写已有片段： 
curl -X POST https://api.example.com/api/v1/music/generate \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[桥段]\n故事从这里继续",
    "tags": "流行",
    "continue_clip_id": "clip-abc123",
    "continue_at": 60
  }'

​
典型流程

  1. 调用本接口 → 获取 task_id
  2. 每 5 秒轮询 POST /api/v1/task/{task_id}
  3. 当 status = "completed" 时，读取 results[].audio_url
  4. 文件在 retention_days 后过期 — 请及时下载