Suno 音乐任务代理协议

小白：这是本站任务代理协议

/suno/* 是本站任务代理协议，不是 Suno 官方公开 API。Suno 官方帮助中心说明文字生成音乐、上传音频和编辑等产品能力，但不定义本站的 submit/music、fetch、动作名或返回结构。实际可用动作和模型取决于本站渠道配置，应先在模型广场确认；内部计费或映射标识可能显示为 suno_music，不要把它当成 Suno 官方模型 ID。

最小音乐任务

music 动作支持描述模式或自定义歌词。下面显式给出标题、风格和伴奏开关，便于复现。

Copycreate=$(curl -sS "$BASE_URL/suno/submit/music" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpt_description_prompt":"温暖的独立民谣，主题是雨后回家",
    "title":"雨后归途",
    "tags":"indie folk, warm acoustic",
    "make_instrumental":false
  }')

task_id=$(printf '%s' "$create" | jq -r '.data')
test -n "$task_id" && test "$task_id" != "null"

兼容提交响应通常为 {"code":"success","data":"<task_id>"}。data 是本站公开任务 ID，不是音频 URL。不要记录完整歌词、声音素材或上游密钥；日志只保留脱敏参数摘要、Request-ID 和任务 ID。

查询状态与读取歌曲

Copycurl "$BASE_URL/suno/fetch/$task_id" \
  -H "Authorization: Bearer $API_KEY"

规范查询模式写作 GET /suno/fetch/{task_id}。查询响应外层包含 code 和 data，任务对象包含 task_id、status、progress、fail_reason、时间戳和结果 data。本站标准状态为 NOT_START、SUBMITTED、QUEUED、IN_PROGRESS、SUCCESS、FAILURE；只有后两者是终态。上游的 queueing、processing、completed、failed 等值会被标准化，客户端只处理本站返回值。

SUCCESS 后再读取歌曲数组中的 audio_url、video_url、image_url、标题和元数据。FAILURE 时记录 fail_reason，不要继续轮询。采用有上限的退避和抖动，并给长任务设置业务超时，而不是高频固定查询。

动作、续写与上传边界

代理动作主要包括 music、lyrics、concat 和 uploads；歌词任务要求 prompt，续写可能需要 task_id、continue_clip_id 和 continue_at。另有 /suno/api/* 和 /v1/suno/* 兼容入口，但其字段与上游类型更复杂。新项目应固定一套契约，除非迁移测试证明两套返回能被正确区分。

上传音频前校验格式、时长、字节数、声道与版权授权。URL 上传必须阻断内网和云元数据地址、限制重定向与下载大小；不要在内存中同时保留完整上传、Base64 和转码副本。

计费、重试与结果生命周期

一次生成可能返回多首歌曲。成本核对需要保存动作、模型映射、生成数量、续写/上传参数、任务 ID 和账单日志。提交超时并不等于未受理，业务侧用幂等记录防止重复创建；参数、审核和版权失败不应重试，429 应退避，临时 5xx 才进入有限重试预算。

音频、视频与封面 URL 可能过期。任务成功后流式复制到自有存储，记录 MIME、大小、哈希、时长、来源任务、权限和删除时间。对用户声音、歌词草稿和未发布歌曲实施最小权限与明确保留期。

专家：生产质量与版权治理

建立包含提示词遵循、结构、音质、人声、歌词准确性、截断、静音和重复度的固定评测集；模型或渠道变更先做灰度。分别监控提交成功率、排队时长、P95 完成时间、每任务歌曲数、失败原因、重复任务率、保存失败率和单位成功作品成本。声音克隆、上传作品和商业发布应有权利确认、投诉处理、删除和审计流程。