Suno Reverse-Proxy API

Suno 官方没开放 self-serve API，所有"Suno API"都是反代中转。本 skill 覆盖调用规范、轮询、错误处理。

写词、风格设计、Suno 中文坑等创作侧问题 → 用 write-lyric skill。

When to load

提交 Suno 生成任务（POST /api/v1/generate）
轮询任务状态、下载结果
排查 500 / GENERATE_AUDIO_FAILED / AuthorizeFailed 等错误
切换中转商（SunoAPI.org / 向量引擎 / gcui-art 等）
用 replace-section / extend / cover / 分轨 / WAV / MV
写脚本批量跑 Suno 任务

Quick reference

SunoAPI.org（最完整）：

Base:       https://api.sunoapi.org
Auth:       Authorization: Bearer <key>
Submit:     POST /api/v1/generate
Cover:      POST /api/v1/generate/upload-cover
Replace:    POST /api/v1/generate/replace-section
Query:      GET  /api/v1/generate/record-info?taskId=<id>
Credit:     GET  /api/v1/generate/credit

向量引擎（国内中转）：

Base:       https://api.vectorengine.cn
Auth:       Authorization: Bearer <key>
Submit:     POST /suno/submit/music
Query:      GET  /suno/fetch/<taskId>  or  POST /suno/fetch  body {ids: [...]}

完整 endpoint、字段、错误码、bash 轮询脚本：读 reference/sunoapi-org-api.md。

Key gotchas（这局踩过的）

callBackUrl 必填——可填 dummy https://httpbin.org/post
style ≤ 200 字符——超长直接 500 Internal Error，错误信息不会告诉你长了
V4_5 比 V5 稳——V5 / V5_5 任务失败率高 3-5 倍
任务状态轮询——除 SUCCESS 外，GENERATE_AUDIO_FAILED SENSITIVE_WORD_ERROR CREATE_TASK_FAILED FAILED FAILURE 也都是终止状态，不要漏判
macOS bash 3.x 不支持 declare -A——轮询脚本要用 case 语法或迁到 zsh
文件保留 14 天——返回的 mp3/jpeg URL 过期前必须下载备份
一次任务返 2 条 clip（A/B 候选）

Standard workflow

1. 准备 body.json（customMode/title/style/prompt/model/callBackUrl）
2. POST /generate → 拿 taskId
3. 后台轮询 /record-info?taskId=...   (15s 间隔，80 次封顶)
4. status==SUCCESS → 解析 sunoData[] 拿 audioUrl
5. curl 下载到 ~/Downloads/<title>-<A|B>.mp3
6. 失败重试：缩 style → 退一档 model → 换中转

Authentication

凭据存 OS keyring（service claude-secrets），常用条目：

sunoapi-org — SunoAPI.org Bearer token (32 字符 hex)
向量-vector — 向量引擎 sk-xxx key

读取（Python）：

import keyring
key = keyring.get_password('claude-secrets', 'sunoapi-org')

读取（bash）：

SAO=$(~/.claude/venv/bin/python3 -c "import keyring; print(keyring.get_password('claude-secrets','sunoapi-org'),end='')")
curl -H "Authorization: Bearer $SAO" ...

绝不在命令行参数 / 日志 / 提交文件里明文写 key。

Reference index

文件	内容
reference/sunoapi-org-api.md	SunoAPI.org 完整 spec、错误码表、bash 兼容轮询脚本、与其他中转对比

Related skills

write-lyric — 写词、风格 tag 设计、中文 Suno 坑、人声/器乐描述
secret-handling — keyring 密钥管理（这个 skill 自动加载）

Anti-patterns

❌ 把 API key 明文放进 body.json / git / 命令行参数
❌ 轮询脚本用 declare -A（macOS 3.x 死）
❌ 状态机只判 SUCCESS/FAILED 漏判 GENERATE_AUDIO_FAILED
❌ 500 Internal Error 死循环重试不缩 style 不退 model
❌ 同步阻塞调 /generate（Suno 任务平均 60-180 秒，用后台轮询）
❌ 不下载就关电脑（14 天后链接死）

@gao_sean/suno-api