文档 / 音乐系列 / Suno / 音乐生成
音乐生成POSTSunoMUSICAsync Tasks
翻唱歌曲
基于已有歌曲片段生成翻唱版本，支持局部时间范围和自定义生成参数。
Bearer API KeyJSON服务端调用
用途#
通过 POST /v1/music/cover 为已有歌曲片段生成新的翻唱版本。
clip_id 的来源#
clip_id 用于指定被翻唱的素材,来源有两种,任选其一:
| 来源 | 获取方式 | 适用场景 |
|---|---|---|
| 上传的音频 | 先调用上传音频,任务完成后从结果中取出 clip_id | 翻唱本地文件或自有歌曲 |
| Suno 生成的歌曲 | Suno 系音乐任务(suno_music 生成、续写、翻唱等)完成后的 data[].id 即 clip_id | 对已有作品二次创作,例如直接翻唱 suno_music 生成的歌曲 |
两类 clip_id 都是 Suno 生态内的 clip,在本接口中用法完全相同,可直接互换。
clip_id 必须是 Suno 的 clip。其他音乐服务(如 stepaudio-3-music)虽然同样走 /v1/music/generations 入口,但其返回的 data[].id 不是 Suno clip,不能用于翻唱等 Suno 二次加工接口。
请求字段#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
clip_id | string | 是 | 要翻唱的歌曲片段 ID,来源见上方「clip_id 的来源」 |
prompt | string | 是 | 歌词或创作提示;上游任务必需该字段 |
title | string | 否 | 新歌曲标题 |
style | string | 否 | 曲风、人声和制作描述 |
instrumental | boolean | 否 | 是否生成纯音乐 |
cover_start_s | number | 否 | 翻唱区间起点，单位秒 |
cover_end_s | number | 否 | 翻唱区间终点，单位秒 |
metadata | object | 否 | 可包含 lyrics_mode、vocal_gender 和 control_sliders |
callback_url | string | 否 | 任务完成或失败时接收通知的 HTTPS 地址 |
如需指定区间，cover_start_s 与 cover_end_s 必须同时填写，且结束时间大于开始时间。
请求示例#
bash
curl -X POST 'https://api.apimax.ai/v1/music/cover' \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"clip_id": "2e83eef3-d3c3-4eb4-9695-ea7d8e125058",
"prompt": "Keep the melody and use a softer vocal delivery",
"title": "My Song - Acoustic Cover",
"style": "acoustic pop, warm female vocal",
"instrumental": false,
"callback_url": "https://your-app.example/music-callback"
}'clip_id 会映射为上游的 cover_clip_id；旧客户端也可使用 cover_clip_id 或 continue_clip_id。
提交响应#
提交成功后会立即返回任务 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 时，也可以等待回调通知。
完成响应示例（任务完成后 data 包含两个候选结果，任选其一使用即可）：
json
{
"id": "task_UT4HcNdILmtMZIS3ttl2yczzC8a9rRMy",
"object": "task",
"type": "music",
"platform": "music",
"status": "completed",
"progress": 100,
"model": "suno_cover",
"created_at": 1791338243,
"started_at": 1791338255,
"finished_at": 1791338285,
"data": [
{
"id": "48f0e269-cdcd-4ae4-a175-5af03847a8ba",
"audio_url": "https://media.example/cdn/48f0e269-cdcd-4ae4-a175-5af03847a8ba.m4a",
"image_url": "https://media.example/image_48f0e269-cdcd-4ae4-a175-5af03847a8ba.jpeg",
"title": "My Song",
"duration": 76.36,
"status": "complete",
"model_name": "suno_cover",
"provider": "suno",
"created_at": "2026-10-07T01:57:25.084Z",
"metadata": { "duration": 76.36, "prompt": "hi" }
},
{
"id": "b007358f-a179-4199-bb41-0599a0579e0e",
"audio_url": "https://media.example/cdn/b007358f-a179-4199-bb41-0599a0579e0e.m4a",
"image_url": "https://media.example/image_b007358f-a179-4199-bb41-0599a0579e0e.jpeg",
"title": "My Song",
"duration": 129.96,
"status": "complete",
"model_name": "suno_cover",
"provider": "suno",
"created_at": "2026-10-07T01:57:25.084Z",
"metadata": { "duration": 129.96, "prompt": "hi" }
}
]
}in_progress 阶段可能提前返回可预览音频，但仍应继续查询至终态。