Suno API 任务信息

查询 Suno 音乐生成任务的状态和结果。

curl --request GET \
  --url https://api.crun.ai/api/v1/client/job/TaskInfo \
  --header 'x-api-key: <api-key>'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "running",
    "param": {
      "model": "suno/music-generate",
      "callback_url": null,
      "input": {
        "mode": "custom",
        "model": "v5",
        "instrumental": false,
        "title": "Midnight Addiction",
        "tags": "Western R&B, female vocal, dark, sensual",
        "lyrics": "[Verse 1] I still taste your words in the dark..."
      }
    },
    "create_at": 1768900378,
    "result": null,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

GET

api

client

job

TaskInfo

查询 Suno 音乐生成任务的状态和结果。

curl --request GET \
  --url https://api.crun.ai/api/v1/client/job/TaskInfo \
  --header 'x-api-key: <api-key>'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "running",
    "param": {
      "model": "suno/music-generate",
      "callback_url": null,
      "input": {
        "mode": "custom",
        "model": "v5",
        "instrumental": false,
        "title": "Midnight Addiction",
        "tags": "Western R&B, female vocal, dark, sensual",
        "lyrics": "[Verse 1] I still taste your words in the dark..."
      }
    },
    "create_at": 1768900378,
    "result": null,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

API 接口

GET https://api.crun.ai/api/v1/client/job/TaskInfo

此接口用于查询通过 /api/v1/client/job/CreateTask API 创建的 Suno 音乐任务的执行状态，并获取任务结果。它与通用任务查询使用相同的接口、参数和任务状态枚举，但当任务成功时，会在任务结果中额外返回 Suno 专属的 suno_data 数组。

查询参数

task_id

string

必填

创建任务时返回的唯一任务标识符。示例：task_12345678

请求示例

curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=task_12345678" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json"

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "running",
    "param": {
      "model": "suno/music-generate",
      "callback_url": null,
      "input": {
        "mode": "custom",
        "model": "v5",
        "instrumental": false,
        "title": "Midnight Addiction",
        "tags": "Western R&B, female vocal, dark, sensual",
        "lyrics": "[Verse 1] I still taste your words in the dark..."
      }
    },
    "create_at": 1768900378,
    "result": null,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

响应格式

code

integer

响应状态码。200 表示请求已成功处理（无论任务执行结果如何，只要任务被找到并返回）。

message

string

响应消息。通常为 "success"。

data

object

包含所有任务信息的任务数据对象。

显示 data 属性

task_id

string

任务的唯一标识符。

provider

string

模型提供方名称。示例：Suno

model_version

string

创建任务时使用的具体模型版本。

status

string

任务当前状态。详情请参见下方的任务状态枚举。可能的值：pending、running、success、failed

param

object

创建任务时使用的原始参数。

显示 param 属性

model

string

创建任务时使用的模型标识符。

callback_url

string | null

为此任务配置的 Webhook 回调 URL。

input

object

模型专属的输入参数。其结构会因所选模型而异。

result

object | null

任务生成结果。仅当任务状态为 success 或 failed 时才会返回有效值；否则返回 null。

显示 result 属性

code

integer

任务生成结果状态码。200 表示生成成功。非 200 值表示生成失败。

message

string

任务成功或失败的说明。

media_urls

array<string>

生成的音乐媒体 URL。仅在状态为 success 时返回。

suno_data

array<SunoMusicItem>

Suno 音乐项目。仅在任务状态为 success 时返回。

create_at

integer

任务创建时的 Unix 时间戳（秒）。

complete_at

integer | null

任务完成时的 Unix 时间戳（秒）。如果任务尚未完成，则为 null。

duration_s

integer | null

任务执行耗时，单位为秒。如果任务尚未完成，则为 null。

source

string

任务创建来源。

SunoMusicItem 对象

suno_id

string

Suno 音乐 ID

title

string

音乐标题

prompt

string

用于生成音乐的歌词或提示词。

任务状态枚举

状态	描述	操作
`pending`	任务正在队列中等待处理	继续轮询
`running`	任务正在处理中	继续轮询
`success`	任务已成功完成	访问 `result.suno_data` 获取 Suno 音乐项目，或访问 result.media_url 获取结果
`failed`	任务失败	访问 result 对象查看错误码和错误消息。

获取任务结果最佳实践

推荐轮询间隔

轮询间隔：使用 15 到 30 秒的轮询间隔
动态调整间隔：对于长时间运行的音频生成任务，可以考虑动态增加轮询间隔
延迟首次轮询：在首次检查状态前至少等待一个轮询间隔，以减少不必要的请求
最大轮询时长：15-20 分钟后停止轮询并进行排查

过于频繁的轮询可能会触发请求频率限制。生产环境建议使用回调。

使用回调替代轮询

对于生产应用，我们强烈建议在创建任务时使用 callback_url 参数：

无需轮询：你的服务器会自动接收通知
降低 API 成本：避免持续轮询请求
更好的性能：任务完成后立即通知
降低延迟：完成与通知之间没有轮询等待延迟

推荐方式

处理已完成任务

当 status 为 success 时：

从响应中的 result 字段获取任务结果
从 result.suno_data 中提取 Suno 音乐项目
从每个项目的 suno_audio_url 下载音频
将结果元数据持久化到你的存储或数据库中

重要：生成的媒体 URL（非 Suno 原始 URL）通常会在 14 天后被永久删除

常见错误码

Code	描述	解决方案
`401`	未授权 - API Key 无效或缺失	检查你的 API Key
`404`	任务未找到	确认 task_id 是否正确
`429`	超出请求频率限制	降低请求频率
`500`	内部服务器错误	几分钟后重试
`501`	生成失败	查看 `result` 对象以获取错误码和错误消息。

速率限制

最大查询频率：每个账户每秒最多 15 次请求
推荐间隔：每次轮询间隔 15-30 秒

Suno 快速开始

了解如何调用 Suno 模型

生成音乐

根据文本提示词创建具有多样风格的歌曲。

扩展音乐

无缝延续并扩展现有音乐。

音乐翻唱

使用新的风格或声音重新创作歌曲。

授权

x-api-key

string

header

必填

所有 API 都需要通过 API Key 进行身份验证。

获取 API Key：

访问 API Key 管理页面获取你的 API Key

使用方式：添加到请求头：

x-api-key: YOUR_API_KEY

注意：

请妥善保管你的 API Key，不要与他人共享
如果你怀疑 API Key 已泄露，请立即在管理页面中重置

查询参数

task_id

string

必填

用于获取任务结果的任务 ID。

Required string length: 36

示例:

"task_1234567"

响应

任务信息获取成功，或任务未找到。

code

integer

必填

响应状态码

200：成功 - 请求已成功处理
401：未授权 - 身份验证凭证缺失或无效
402：积分不足 - 账户没有足够的积分执行该操作
404：未找到 - 请求的资源或接口不存在
422：验证错误 - 请求参数未通过验证检查
429：请求频率受限 - 已超过该资源的请求限制
455：服务不可用 - 系统当前正在维护
500：服务器错误 - 处理请求时发生意外错误
501：生成失败 - 内容生成任务失败
505：功能已禁用 - 请求的功能当前已被禁用

message

string

必填

响应消息

data

object

任务记录和结果信息。

Show child attributes

Persona 生成人声分离任务信息

​API 接口

​查询参数

​请求示例

​响应格式

​SunoMusicItem 对象

​任务状态枚举

​获取任务结果最佳实践

​常见错误码

​速率限制

​相关资源

Suno 快速开始

生成音乐

扩展音乐

音乐翻唱

授权

查询参数

响应

API 接口

查询参数

请求示例

响应格式

SunoMusicItem 对象

任务状态枚举

获取任务结果最佳实践

常见错误码

速率限制

相关资源