# Suno 音乐生成 API 对接文档 ## 基础信息 - 基础域名：`https://api.apiverse.ai` - 鉴权方式：`Authorization: Bearer ` - Content-Type：`application/json` - 路由前缀：`/api/v2/open/aigc/suno` 所有 Suno 接口均通过上述路由前缀访问，请求体字段和查询参数会按原字段转发，不会裁剪可选参数。 ## 快速示例 ### 生成音乐 ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/suno/generate" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "prompt": "A calm and relaxing piano track with soft melodies", "style": "Classical", "title": "Peaceful Piano Meditation", "customMode": true, "instrumental": true, "model": "V5", "callBackUrl": "https://api.apiverse.ai/callback", "negativeTags": "", "vocalGender": "f", "styleWeight": 0.65, "weirdnessConstraint": 0.65, "audioWeight": 0.65, "personaId": "" }' ``` ### 查询音乐任务 ```bash curl "https://api.apiverse.ai/api/v2/open/aigc/suno/generate/record-info?taskId=" \ -H "Authorization: Bearer " ``` ## 接口列表 | 能力 | 方法 | 路径 | | ---------------- | ---- | ------------------------------------------------------------------- | | 生成音乐 | POST | `/api/v2/open/aigc/suno/generate` | | 获取音乐详情 | GET | `/api/v2/open/aigc/suno/generate/record-info?taskId=` | | 延长音乐 | POST | `/api/v2/open/aigc/suno/generate/extend` | | 替换音乐分区 | POST | `/api/v2/open/aigc/suno/generate/replace-section` | | 生成声音 | POST | `/api/v2/open/aigc/suno/generate/sounds` | | 获取时间戳歌词 | POST | `/api/v2/open/aigc/suno/generate/get-timestamped-lyrics` | | 上传并翻唱音乐 | POST | `/api/v2/open/aigc/suno/generate/upload-cover` | | 上传并扩展音乐 | POST | `/api/v2/open/aigc/suno/generate/upload-extend` | | 添加伴奏 | POST | `/api/v2/open/aigc/suno/generate/add-instrumental` | | 添加人声 | POST | `/api/v2/open/aigc/suno/generate/add-vocals` | | 生成混音音乐 | POST | `/api/v2/open/aigc/suno/generate/mashup` | | 生成 Persona | POST | `/api/v2/open/aigc/suno/generate/generate-persona` | | 生成歌词 | POST | `/api/v2/open/aigc/suno/lyrics` | | 获取歌词详情 | GET | `/api/v2/open/aigc/suno/lyrics/record-info?taskId=` | | 生成音乐封面 | POST | `/api/v2/open/aigc/suno/cover/generate` | | 获取音乐封面详情 | GET | `/api/v2/open/aigc/suno/cover/record-info?taskId=` | | 人声和乐器分离 | POST | `/api/v2/open/aigc/suno/vocal-removal/generate` | | 获取分离详情 | GET | `/api/v2/open/aigc/suno/vocal-removal/record-info?taskId=` | | 转换 WAV | POST | `/api/v2/open/aigc/suno/wav/generate` | | 获取 WAV 详情 | GET | `/api/v2/open/aigc/suno/wav/record-info?taskId=` | | 创建音乐视频 | POST | `/api/v2/open/aigc/suno/mp4/generate` | | 获取音乐视频详情 | GET | `/api/v2/open/aigc/suno/mp4/record-info?taskId=` | | 生成 MIDI | POST | `/api/v2/open/aigc/suno/midi/generate` | | 获取 MIDI 详情 | GET | `/api/v2/open/aigc/suno/midi/record-info?taskId=` | | 优化音乐风格 | POST | `/api/v2/open/aigc/suno/style/generate` | ## 参数说明 ### 1. 生成音乐 **POST** `/api/v2/open/aigc/suno/generate` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | | prompt | string | 是 | 音乐内容提示词。`customMode=true` 且 `instrumental=false` 时作为歌词使用；`customMode=false` 时作为创意提示。 | | style | string | 条件必填 | 音乐风格。`customMode=true` 时必填；`customMode=false` 时应留空或不传。 | | title | string | 条件必填 | 音乐标题。`customMode=true` 时必填。 | | customMode | boolean | 是 | 是否启用自定义模式。 | | instrumental | boolean | 是 | 是否生成纯音乐。 | | model | string | 是 | 模型版本：`V4` / `V4_5` / `V4_5PLUS` / `V4_5ALL` / `V5` / `V5_5`。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | negativeTags | string | 否 | 需要排除的风格或特征。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`，仅自定义模式下建议使用。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`，建议保留两位小数。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | | personaId | string | 否 | Persona ID，用于套用特定音乐人格。 | ### 2. 获取音乐详情 **GET** `/api/v2/open/aigc/suno/generate/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | --------------------------------------------------- | | taskId | query | string | 是 | 生成、延长、上传翻唱、上传扩展等任务返回的任务 ID。 | ### 3. 延长音乐 **POST** `/api/v2/open/aigc/suno/generate/extend` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------- | -------- | ------------------------------------------------------------------ | | defaultParamFlag | boolean | 是 | `true` 表示使用本次请求传入的新参数；`false` 表示沿用源音频参数。 | | audioId | string | 是 | 要延长的音频 ID。 | | model | string | 是 | 模型版本：`V4` / `V4_5` / `V4_5PLUS` / `V4_5ALL` / `V5` / `V5_5`。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | prompt | string | 条件必填 | `defaultParamFlag=true` 时必填，描述延长部分内容。 | | style | string | 条件必填 | `defaultParamFlag=true` 时必填，描述音乐风格。 | | title | string | 条件必填 | `defaultParamFlag=true` 时必填。 | | continueAt | number | 条件必填 | `defaultParamFlag=true` 时必填，从源音频第几秒开始延长。 | | instrumental | boolean | 否 | 是否生成纯音乐。 | | negativeTags | string | 否 | 需要排除的风格或特征。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | | personaId | string | 否 | Persona ID。 | ### 4. 生成歌词 **POST** `/api/v2/open/aigc/suno/lyrics` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ------------------------------------------------ | | prompt | string | 是 | 歌词主题、情绪、风格或故事描述。 | | callBackUrl | string | 否 | 歌词生成完成回调地址；不传时可通过查询接口轮询。 | ### 5. 获取歌词详情 **GET** `/api/v2/open/aigc/suno/lyrics/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | --------------------------- | | taskId | query | string | 是 | 生成歌词接口返回的任务 ID。 | ### 6. 生成声音 **POST** `/api/v2/open/aigc/suno/generate/sounds` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- | -------------------------------------- | | prompt | string | 是 | 声音内容提示词，建议 500 字符以内。 | | model | string | 是 | 模型版本：`V5` / `V5_5`。 | | soundLoop | boolean | 否 | 是否生成循环音频，默认 `false`。 | | soundTempo | integer | 否 | BPM，范围 `1` 到 `300`；不传表示自动。 | | soundKey | string | 否 | 调性，如 `C`、`D#m`、`Any`。 | | grabLyrics | boolean | 否 | 是否抓取歌词字幕。 | | callBackUrl | string | 否 | 任务状态回调地址。 | ### 7. 获取时间戳歌词 **POST** `/api/v2/open/aigc/suno/generate/get-timestamped-lyrics` | 参数 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | --------------------------- | | taskId | string | 是 | 音乐生成任务 ID。 | | audioId | string | 是 | 要获取时间戳歌词的音频 ID。 | ### 8. 替换音乐分区 **POST** `/api/v2/open/aigc/suno/generate/replace-section` | 参数 | 类型 | 必填 | 说明 | | ------------ | ------ | ---- | ---------------------- | | taskId | string | 是 | 源音乐任务 ID。 | | audioId | string | 是 | 要替换片段的音频 ID。 | | prompt | string | 是 | 替换片段的新歌词。 | | tags | string | 是 | 音乐风格标签。 | | title | string | 是 | 音乐标题。 | | infillStartS | number | 是 | 替换起始时间，单位秒。 | | infillEndS | number | 是 | 替换结束时间，单位秒。 | | fullLyrics | string | 是 | 替换后的完整歌词。 | | negativeTags | string | 否 | 需要排除的风格或特征。 | | callBackUrl | string | 否 | 任务状态回调地址。 | ### 9. 上传并翻唱音乐 **POST** `/api/v2/open/aigc/suno/generate/upload-cover` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------- | -------- | ------------------------------------------------------------------ | | uploadUrl | string | 是 | 可公开访问的源音频 URL。 | | customMode | boolean | 是 | 是否启用自定义模式。 | | instrumental | boolean | 是 | 是否生成纯音乐。 | | model | string | 是 | 模型版本：`V4` / `V4_5` / `V4_5PLUS` / `V4_5ALL` / `V5` / `V5_5`。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | prompt | string | 条件必填 | `customMode=true` 且 `instrumental=false` 时必填。 | | style | string | 条件必填 | `customMode=true` 时必填。 | | title | string | 条件必填 | `customMode=true` 时必填。 | | negativeTags | string | 否 | 需要排除的风格或特征。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | | personaId | string | 否 | Persona ID。 | ### 10. 上传并扩展音乐 **POST** `/api/v2/open/aigc/suno/generate/upload-extend` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------- | -------- | ------------------------------------------------------------------ | | uploadUrl | string | 是 | 可公开访问的源音频 URL。 | | defaultParamFlag | boolean | 是 | `true` 表示使用本次请求传入的新参数；`false` 表示沿用源音频参数。 | | model | string | 是 | 模型版本：`V4` / `V4_5` / `V4_5PLUS` / `V4_5ALL` / `V5` / `V5_5`。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | instrumental | boolean | 否 | 是否生成纯音乐。 | | prompt | string | 条件必填 | `defaultParamFlag=true` 时必填。 | | style | string | 条件必填 | `defaultParamFlag=true` 时必填。 | | title | string | 条件必填 | `defaultParamFlag=true` 时必填。 | | continueAt | number | 条件必填 | `defaultParamFlag=true` 时必填，从源音频第几秒开始扩展。 | | negativeTags | string | 否 | 需要排除的风格或特征。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | | personaId | string | 否 | Persona ID。 | ### 11. 添加伴奏 **POST** `/api/v2/open/aigc/suno/generate/add-instrumental` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | ------------------------------------------------------- | | uploadUrl | string | 是 | 要添加伴奏的源音频 URL。 | | title | string | 是 | 生成音乐标题。 | | negativeTags | string | 是 | 需要排除的风格或特征。 | | tags | string | 是 | 期望包含的音乐风格标签。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | model | string | 否 | 模型版本：`V4` / `V4_5` / `V4_5PLUS`，默认 `V4_5PLUS`。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | ### 12. 添加人声 **POST** `/api/v2/open/aigc/suno/generate/add-vocals` | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | ------------------------------------------------------- | | prompt | string | 是 | 人声演唱内容或歌词提示。 | | title | string | 是 | 音乐标题。 | | negativeTags | string | 是 | 需要排除的风格或特征。 | | style | string | 是 | 音乐风格。 | | uploadUrl | string | 是 | 要添加人声的源音频 URL。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | model | string | 否 | 模型版本：`V4` / `V4_5` / `V4_5PLUS`，默认 `V4_5PLUS`。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`。 | ### 13. 生成混音音乐 **POST** `/api/v2/open/aigc/suno/generate/mashup` | 参数 | 类型 | 必填 | 说明 | | ------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------- | | uploadUrlList | string[] | 是 | 要混音的音频 URL 数组，必须包含 2 个 URL。 | | customMode | boolean | 是 | 是否启用自定义模式。 | | model | string | 是 | 模型版本：`V4` / `V4_5` / `V4_5PLUS` / `V4_5ALL` / `V5` / `V5_5`。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | style | string | 条件必填 | 音乐风格。`customMode=true` 时必填；`customMode=false` 时应留空或不传。 | | title | string | 条件必填 | 音乐标题。`customMode=true` 时必填。 | | prompt | string | 条件必填 | `customMode=true` 且 `instrumental=false` 时必填，作为歌词使用；`customMode=false` 时作为创意提示。 | | instrumental | boolean | 否 | 是否生成纯音乐。 | | vocalGender | string | 否 | 人声性别偏好：`m` / `f`，仅 `customMode=true` 时生效。 | | styleWeight | number | 否 | 风格遵循强度，范围 `0` 到 `1`，仅 `customMode=true` 时生效。 | | weirdnessConstraint | number | 否 | 创意偏离程度，范围 `0` 到 `1`，仅 `customMode=true` 时生效。 | | audioWeight | number | 否 | 音频要素权重，范围 `0` 到 `1`，仅 `customMode=true` 时生效。 | ### 14. 生成 Persona **POST** `/api/v2/open/aigc/suno/generate/generate-persona` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ---------------------------------------- | | taskId | string | 是 | 已完成音乐任务 ID。 | | audioId | string | 是 | 用于创建 Persona 的音频 ID。 | | name | string | 是 | Persona 名称。 | | description | string | 是 | Persona 的音乐特征、风格和人声特质说明。 | ### 15. 生成音乐封面 **POST** `/api/v2/open/aigc/suno/cover/generate` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ---------------------- | | taskId | string | 是 | 原音乐任务 ID。 | | callBackUrl | string | 否 | 封面生成完成回调地址。 | ### 16. 获取音乐封面详情 **GET** `/api/v2/open/aigc/suno/cover/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | ----------------- | | taskId | query | string | 是 | 封面生成任务 ID。 | ### 17. 人声和乐器分离 **POST** `/api/v2/open/aigc/suno/vocal-removal/generate` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ----------------------------------------------------------------------------------------- | | taskId | string | 是 | 音乐生成任务 ID。 | | audioId | string | 是 | 要分离的音频 ID。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | type | string | 否 | 分离类型：`separate_vocal`（人声/伴奏）或 `split_stem`（多音轨），默认 `separate_vocal`。 | ### 18. 获取分离详情 **GET** `/api/v2/open/aigc/suno/vocal-removal/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | ------------- | | taskId | query | string | 是 | 分离任务 ID。 | ### 19. 转换 WAV **POST** `/api/v2/open/aigc/suno/wav/generate` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ------------------ | | taskId | string | 是 | 音乐生成任务 ID。 | | audioId | string | 是 | 要转换的音频 ID。 | | callBackUrl | string | 是 | 任务状态回调地址。 | ### 20. 获取 WAV 详情 **GET** `/api/v2/open/aigc/suno/wav/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | ----------------- | | taskId | query | string | 是 | WAV 转换任务 ID。 | ### 21. 创建音乐视频 **POST** `/api/v2/open/aigc/suno/mp4/generate` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ------------------------------------------ | | taskId | string | 是 | 音乐生成任务 ID。 | | audioId | string | 是 | 要生成视频的音频 ID。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | author | string | 否 | 视频封面展示的作者名，最多 50 字符。 | | domainName | string | 否 | 视频底部展示的品牌或站点名，最多 50 字符。 | ### 22. 获取音乐视频详情 **GET** `/api/v2/open/aigc/suno/mp4/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | ----------------- | | taskId | query | string | 是 | 音乐视频任务 ID。 | ### 23. 生成 MIDI **POST** `/api/v2/open/aigc/suno/midi/generate` | 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | --------------------------------------------------- | | taskId | string | 是 | 已完成人声/乐器分离任务 ID。 | | callBackUrl | string | 是 | 任务状态回调地址。 | | audioId | string | 否 | 要生成 MIDI 的分离音轨 ID；不传时通常处理默认音轨。 | ### 24. 获取 MIDI 详情 **GET** `/api/v2/open/aigc/suno/midi/record-info?taskId=` | 参数 | 位置 | 类型 | 必填 | 说明 | | ------ | ----- | ------ | ---- | -------------- | | taskId | query | string | 是 | MIDI 任务 ID。 | ### 25. 优化音乐风格 **POST** `/api/v2/open/aigc/suno/style/generate` | 参数 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ------------------------------------------ | | content | string | 是 | 待优化的风格描述，例如 `Pop, Mysterious`。 | ## 响应格式 接口响应保持原始 JSON 格式。创建类接口通常返回 `data.taskId`，查询类接口通常返回 `data.status`、`data.response`、`data.response.sunoData` 等字段。 ```json { "code": 200, "msg": "success", "data": { "taskId": "task_xxx" } } ```