Suno API cURL 与 Postman：发出第一个请求

直接答案：先用 Postman 或 cURL 调 POST /api/music/create，建议在请求体加入 "accept_mode":"async"，并带上唯一的 Idempotency-Key。保存返回的 request_id，轮询 GET /api/music/requests/{request_id}；拿到真实 song_id 后，再用歌曲查询和下载接口继续。

先准备两个值

所有请求都只用两个核心配置：站点地址和 API Key。下面用环境变量保存，避免把 Key 写进脚本或提交到 Git。

cURL：创建异步生成任务

异步受理适合 Postman、命令行和短连接客户端。接口立即返回受理回执，生成在后台继续，不会因为客户端等待太久而误判失败。

curl -X POST "https://www.suno-api.io/api/music/create"   -H "Authorization: Bearer $SUNO_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: demo-20261027-001"   -d '{
    "description": "温暖的中文流行，钢琴前奏，女声",
    "model": "suno-v6",
    "accept_mode": "async"
  }'

成功受理通常返回 HTTP 202。重点字段是 data.request_id、data.status 和 data.tasks。此时还没有真实歌曲 ID，不要把 request_id 或 tasks[].index 当成 song_id。

{
  "success": true,
  "data": {
    "request_id": "ac_2026102709000000000000000001",
    "status": "queued",
    "tasks": [
      {"index": 0, "status": "queued"},
      {"index": 1, "status": "queued"}
    ]
  }
}

查询受理进度

curl "https://www.suno-api.io/api/music/requests/ac_2026102709000000000000000001"   -H "Authorization: Bearer $SUNO_API_KEY"

建议每 5 秒查询一次，并逐步退避到 10 秒左右。queued 和 processing 继续等待；partial 表示已有部分歌曲完成；completed 时可从各任务的 song_id 进入歌曲查询；failed 时读取 error_message，不要重新创建任务。

Postman 怎么配

1. 新建 Collection，在 Variables 中设置 baseUrl 和 apiKey。
2. 新建 POST 请求：{{baseUrl}}/api/music/create。
3. Headers 增加 Authorization: Bearer {{apiKey}}，以及唯一的 Idempotency-Key。
4. Body 选择 raw → JSON，填入 description、model 和 accept_mode。
5. 在 Tests 中把返回的 request_id 写入环境变量，后续查询请求直接引用。

const body = pm.response.json();
if (body.success && body.data && body.data.request_id) {
  pm.environment.set("requestId", body.data.request_id);
  console.log("request_id:", body.data.request_id);
}

之后新建 GET 请求：{{baseUrl}}/api/music/requests/{{requestId}}。不需要再写 JSON 请求体，但仍要带同一个 Authorization 头。

常见状态码

三个避免重复扣费的习惯

• 每次业务提交生成一个唯一 Idempotency-Key，重放时继续用同一个值。
• 网络超时后先查受理回执或歌曲历史列表，确认订单不存在后再重新提交。
• 创建、查询、下载分别放在三个函数里，避免把生成调用写进轮询循环。

常见问题

Postman 里 API Key 放在哪里？

放在 Authorization 请求头，格式是 Bearer YOUR_API_KEY。不要放进 URL 查询参数，也不要把 Key 当成 JSON 字段。

为什么创建请求没有直接返回歌曲？

因为使用了 accept_mode=async。受理阶段只返回 request_id，真实 song_id 会在受理进度接口中出现。

cURL 返回 401 还是 403？

401 通常是 Key 缺失、格式错误或无效；403 多是 Key 被禁用或账号状态异常。先读错误正文，再决定修 Key、充值或联系支持。

继续阅读：返回字段详解、Python 示例、Node.js 示例、快速开始。

← 返回全部文章