API Reference

旧 Suno 音乐生成

旧 Suno 音乐生成;仅适用于已配置的旧 Suno 渠道。

POST https://api.tu-zi.com/suno/submit/music
预览指南

粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。

预览指南

旧 Suno 音乐生成

更新 · 审核信息

接口与鉴权

POST https://api.tu-zi.com/suno/submit/music

传输方式: json

使用模型调用 API Key。示例凭证为占位符,请从环境变量读取真实密钥。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

调用准备

  • 示例使用本站地址;调用其他站点时,仅替换站点地址,保留完整接口路径。
  • 替换资源占位符 YOUR_PROVIDER_VERSION:任务与请求 ID 从同一账号的真实响应获取,版本和按钮值按关联协议说明填写,不能直接发送占位符。
  • 使用本站令牌页面创建的模型调用密钥。按示例设置环境变量 API_KEY,或替换 YOUR_API_KEY 占位符。

适用限制

协议差异

旧协议提交响应 data 是字符串,v2 是包含 task_id 的对象;不能只替换 URL。

渠道与参数

  • 动作路由、mv 版本、片段 ID 与渠道能力分别核对。
  • 参数表表示当前 DTO 能承载,不保证每个渠道实现全部模式。
  • 新接入在已有 v2 渠道时优先对应 /suno/v2 动作;旧片段 ID 不自动转换成 v2 公开素材 ID。

片段与账号

task_id、continue_clip_id 原样透传,不自动绑定原任务渠道或账号;后续操作需要使用拥有该片段的兼容渠道。

最小请求示例

{
  "gpt_description_prompt": "A calm piano melody",
  "mv": "YOUR_PROVIDER_VERSION",
  "make_instrumental": true
}

如何判断调用成功

先检查 HTTP 状态,再检查正文的业务状态和所需结果字段,不能只看 HTTP 200 或脚本退出码。

  1. 旧 Suno 首先检查 code=success。
  2. 提交后的 data 字符串是任务 ID;查询 data.status 达到 SUCCESS 后再检查 data.data 的媒体结果,FAILURE 时停止。

请求体参数

字段类型必填说明与约束
modelstring否可选模型路由覆盖;默认由动作选择。
promptstring否歌词或提示词;lyrics 动作必填。
gpt_description_promptstring否描述模式提示词,依渠道支持。
mvstring否渠道确认的版本标识;部分渠道必填,勿从模型名猜测。
titlestring否歌曲标题。
tagsstring否风格标签。
make_instrumentalboolean否纯音乐;显式 false 会保留。
task_idstring否渠道约定的任务标识,原样透传;不会自动把本站任务 ID 转换为上游 ID,也不会据此绑定原渠道。
continue_clip_idstring否原结果中的片段 ID,不等同于任务 ID。
continue_atnumber否续写起点(秒);显式 0 会保留。
cover_clip_idstring否Cover 原片段 ID,依渠道支持。
generation_typestring否渠道约定的生成模式,不保证跨渠道兼容。
negative_tagsstring否排除的风格标签。
taskstring否渠道约定的任务模式。
continued_aligned_promptstring否续写对齐提示词。
infill_start_snumber否局部替换起点秒数,依渠道支持。
infill_end_snumber否局部替换终点秒数,依渠道支持。

响应字段

字段类型说明与约束
codestring成功为 success。
datastring本站公开任务 ID;不是 v2 的 data.task_id。

以下为示例响应,部分接口仅展示主要字段;可选字段不保证出现。

{
  "code": "success",
  "data": "task_example"
}

异步任务

  1. 保存 data 字符串任务 ID,用同一凭证 GET /suno/fetch/{task_id} 查询。
  2. data.status 为 SUCCESS / FAILURE 时终止;读取 data.data 中的歌曲、歌词或素材结果。
  3. 创建超时先核查任务记录,避免重复付费提交。

错误处理与重试

检查 HTTP 状态与该协议的错误对象;不要将不同协议的错误字段混用。

  • 401/403: 检查凭证与权限。
  • 429: 区分临时限流、额度不足与服务容量,只有临时故障适合有限退避。
  • 5xx: 检查网关、上游及模型/渠道配置。

错误正文可能含 error/message/code 等字段,以实际协议为准。

  • 查询遇到临时错误时可采用有上限的指数退避;参数、鉴权、额度或配置问题先修复再请求。
  • 创建任务、生成内容、创建或删除密钥等操作不要盲目重试,以免重复计费或重复执行。