跳转到主要内容
GET
/
api
/
v1
/
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": "suno-vocal-separation",
    "status": "running",
    "param": {
      "model": "suno/vocal-separatio",
      "callback_url": null,
      "input": {
        "task_id": "task_12345678",
        "suno_id": "suno_abc123",
        "mode": "vocal"
      }
    },
    "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 人声分离任务的执行状态，并获取任务结果。
它与通用任务查询使用相同的接口、参数和任务状态枚举，但任务结果中不包含 media_urls 或 suno_data。 相反，它会返回一个 media_info 对象，其中包含根据不同分离模式而变化的音频分轨 URL。

​
查询参数

​
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": "suno-vocal-separation",
    "status": "running",
    "param": {
      "model": "suno/vocal-separatio",
      "callback_url": null,
      "input": {
        "task_id": "task_12345678",
        "suno_id": "suno_abc123",
        "mode": "vocal"
      }
    },
    "create_at": 1768900378,
    "result": null,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

​
响应格式

​
code
integer
响应状态码。200 表示请求已成功处理（无论任务执行结果如何，只要任务被找到并返回）。
​
message
string
响应消息。通常为 "success"。
​
data
object
包含所有任务信息的任务数据对象。

​
Media Info 对象

​
origin_url
string
原始音频 URL。
​
vocal_url
string
主人声音频 URL。
​
instrumental_url
string
伴奏部分音频 URL（仅人声模式）。
​
backing_vocals_url
string
和声音频 URL（仅乐器分轨模式）。
​
drums_url
string
鼓组部分音频 URL（仅乐器分轨模式）。
​
bass_url
string
贝斯部分音频 URL（仅乐器分轨模式）。
​
guitar_url
string
吉他部分音频 URL（仅乐器分轨模式）。
​
keyboard_url
string
键盘部分音频 URL（仅乐器分轨模式）。
​
percussion_url
string
打击乐部分音频 URL（仅乐器分轨模式）。
​
strings_url
string
弦乐部分音频 URL（仅乐器分轨模式）。
​
synth_url
string
合成器部分音频 URL（仅乐器分轨模式）。
​
fx_url
string
音效部分音频 URL（仅乐器分轨模式）。
​
brass_url
string
铜管部分音频 URL（仅乐器分轨模式）。
​
woodwinds_url
string
木管部分音频 URL（仅乐器分轨模式）。

​
任务状态枚举

状态描述操作
pending任务正在队列中等待处理继续轮询
running任务正在处理中继续轮询
success任务已成功完成访问 result.media_info 获取分轨 URL
failed任务失败访问 result 对象查看错误码和错误消息。

​
获取任务结果最佳实践

  • 轮询间隔：使用 15 到 30 秒的轮询间隔
  • 动态调整间隔：对于长时间运行的音频处理任务，可以考虑动态增加轮询间隔
  • 延迟首次轮询：在首次检查状态前至少等待一个轮询间隔，以减少不必要的请求
  • 最大轮询时长：15-20 分钟后停止轮询并进行排查
过于频繁的轮询可能会触发请求频率限制。生产环境建议使用回调。
对于生产应用，我们强烈建议在创建任务时使用 callback_url 参数：
  • 无需轮询：你的服务器会自动接收通知
  • 降低 API 成本：避免持续轮询请求
  • 更好的性能：任务完成后立即通知
  • 降低延迟：完成与通知之间没有轮询等待延迟
推荐方式
当 status 为 success 时：
  1. 从响应中的 result 字段获取任务结果
  2. 从 result.media_info 中提取分轨 URL
  3. 将音频文件下载到你自己的存储中
  4. 将结果元数据持久化到你的存储或数据库中
重要：生成的媒体 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：

  1. 访问 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

任务记录和结果信息。