跳转到主要内容
GET
get task status
只有异步接口会返回 taskId。用本接口轮询到终态(success、failed 或 timeout)。同步接口(/wav、/m4a、/timing、/downbeats、/upsampleTags、/lyricsInfill、/persona、/getVoxStem、播放列表创建/追加、session prepare)在当次响应里直接给结果 — 不要对它们轮询 /status。
对照 Suno 总览 — 异步 vs 同步。要看执行该任务的账号是否还可用,调用 检查账号是否离线(GET,同步)。 状态体里始终有 taskId。创建该任务的请求存过网关 x-trace-id 时,响应里还会带 traceId。没有存过 trace id 的任务会省略 traceId。其余字段不变。

任务状态值

轮询最佳实践

轮询时使用指数退避策略:从 2-3 秒间隔开始,然后逐渐增加。音乐生成任务通常需要 30-120 秒,具体取决于任务类型。

授权

Authorization
string
header
必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

查询参数

taskId
string
必填

Task ID

示例:

"1212"

响应

200 - application/json

The task status information

taskId
string
必填

Task id.

示例:

"task_1731a9b2f4"

status
enum<string>
必填

task status

可用选项:
queued,
ready,
running,
stream,
awaiting,
success,
failed,
timeout
createdAt
string<date-time>
必填

Task created time (UTC).

示例:

"2025-08-18T02:30:00.000Z"

traceId
string

Trace id of the request that created this task (gateway x-trace-id). Omitted when that task has no stored trace id. Other fields stay the same.

示例:

"82b093e1-b45d-462d-906e-df066fdd084a"

failReason
string

Failure reason when status=FAILED.

示例:

"Audio source not found."

failCode
number

Failure code when status=FAILED.

示例:

4001

data
object

Data associated with the task.

finishAt
string<date-time>

Task finished time (UTC).

示例:

"2025-08-18T02:35:00.000Z"