Suno v3 API 必须用 X-API-Key 请求头认证，禁用 Bearer Token；payload 需严格为 {"input": ["prompt"], "model": "suno-v3"}；Content-Type 必须设为 application/json；轮询 status 时须处理 "queued"、"generating"、"error" 等状态。
PHP cURL 请求必须携带 X-API-Key 而非 Bearer Token
目前 Suno 官方 API（v3）不接受 Authorization: Bearer <token> 方式认证，所有请求头必须显式传入 X-API-Key。用错认证方式会直接返回 401 Unauthorized，且错误体里不提示具体原因，只含模糊的 {"detail":"Not authenticated"}。
实操建议：
- 确保每次请求的
cURL都调用curl_setopt($ch, CURLOPT_HTTPHEADER, [...])，其中包含'X-API-Key: your_api_key_here' - 不要在 URL 里拼
?key=...，Suno 不支持查询参数传 key - API Key 必须是 Suno Dashboard 生成的 v3 类型密钥（以
sk-...开头），旧版 v2 key 会静默失败
POST /api/suno/v3/generate 返回 422 时检查 payload 结构
Suno 对请求体 JSON 的字段名、嵌套层级、类型极其敏感，422 Unprocessable Entity 几乎全是 payload 格式问题，不是权限或配额问题。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
- 用
"prompt"字段代替必需的"input"（正确字段名是input，类型为字符串数组） -
input写成单个字符串而非数组：错误写法{"input": "happy jazz"}→ 正确写法{"input": ["happy jazz"]} - 漏掉
model字段，或填了不存在的模型名（当前仅支持"suno-v3"，大小写敏感） - 传了 Suno 不识别的字段如
style、tempo，会导致整个 payload 被拒
示例最小合法 payload：
{"input": ["lofi hip hop beat"], "model": "suno-v3"}
PHP json_encode() 后需手动设置 Content-Type 为 application/json
PHP 默认用 Content-Type: text/html 或空值发 POST，而 Suno 强制要求 Content-Type: application/json，否则返回 415 Unsupported Media Type。
实操建议：
- 调用
json_encode()后，务必在CURLOPT_HTTPHEADER中显式加入'Content-Type: application/json' - 避免使用
http_build_query()处理 payload，它会生成application/x-www-form-urlencoded格式，Suno 拒绝解析 - 如果用了 Guzzle，确认设置了
['json' => $data]而非['body' => json_encode($data)]，后者不会自动设 header
轮询 /api/suno/v3/status 时别忽略 status 字段的中间状态
生成任务不是立即完成的，Suno 返回的 status 可能是 "queued"、"generating"、"complete" 或 "error"。很多 PHP 脚本只等 "complete"，却没处理 "error" 导致无限轮询。
关键细节：
- 每次轮询必须检查
status值，遇到"error"应立即终止并读取error_message字段（如有） -
"queued"状态可能持续 10–60 秒，不要设过短的 sleep（如 1 秒），建议首次延迟 3 秒，后续递增到 5 秒 - 响应体中的
audio_url仅在status === "complete"时存在，提前访问会得到null
容易被忽略的是：Suno 的 status 接口不返回 HTTP 错误码，即使任务失败也返回 200 OK，全靠解析 body 判断。
