Suno API 任务信息

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

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

import requests

url = "https://api.crun.ai/api/v1/client/job/TaskInfo"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.crun.ai/api/v1/client/job/TaskInfo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.crun.ai/api/v1/client/job/TaskInfo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.crun.ai/api/v1/client/job/TaskInfo"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.crun.ai/api/v1/client/job/TaskInfo")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.crun.ai/api/v1/client/job/TaskInfo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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,
    "credits": 12,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "success",
    "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": {
      "code": 200,
      "message": "generation success",
      "suno_data": [
        {
          "suno_id": "suno_abc123",
          "title": "Midnight Addiction",
          "prompt": "[Verse 1] I still taste your words in the dark...",
          "tags": "Western R&B, female vocal, dark, sensual",
          "suno_audio_url": "https://example.com/audio.mp3",
          "suno_image_url": "https://example.com/cover.jpg",
          "suno_image_large_url": "https://example.com/cover-large.jpg",
          "suno_model_name": "v5",
          "duration": 123.45,
          "created_at": 1773969602219
        },
        {
          "suno_id": "suno_def456",
          "title": "Neon Dreams",
          "prompt": "Lo-fi chill instrumental hip hop beat...",
          "tags": "lofi, chill, instrumental",
          "suno_audio_url": "https://example.com/audio-2.mp3",
          "suno_image_url": "https://example.com/cover-2.jpg",
          "suno_image_large_url": "https://example.com/cover-large-2.jpg",
          "suno_model_name": "v5",
          "duration": 118.2,
          "created_at": 1773969602219
        }
      ]
    },
    "credits": 12,
    "duration_s": 137,
    "complete_at": 1768900515,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "failed",
    "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": {
      "code": 501,
      "message": "generation failed"
    },
    "credits": 0,
    "duration_s": 137,
    "complete_at": 1768900515,
    "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>'

import requests

url = "https://api.crun.ai/api/v1/client/job/TaskInfo"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.crun.ai/api/v1/client/job/TaskInfo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.crun.ai/api/v1/client/job/TaskInfo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.crun.ai/api/v1/client/job/TaskInfo"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.crun.ai/api/v1/client/job/TaskInfo")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.crun.ai/api/v1/client/job/TaskInfo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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,
    "credits": 12,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "success",
    "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": {
      "code": 200,
      "message": "generation success",
      "suno_data": [
        {
          "suno_id": "suno_abc123",
          "title": "Midnight Addiction",
          "prompt": "[Verse 1] I still taste your words in the dark...",
          "tags": "Western R&B, female vocal, dark, sensual",
          "suno_audio_url": "https://example.com/audio.mp3",
          "suno_image_url": "https://example.com/cover.jpg",
          "suno_image_large_url": "https://example.com/cover-large.jpg",
          "suno_model_name": "v5",
          "duration": 123.45,
          "created_at": 1773969602219
        },
        {
          "suno_id": "suno_def456",
          "title": "Neon Dreams",
          "prompt": "Lo-fi chill instrumental hip hop beat...",
          "tags": "lofi, chill, instrumental",
          "suno_audio_url": "https://example.com/audio-2.mp3",
          "suno_image_url": "https://example.com/cover-2.jpg",
          "suno_image_large_url": "https://example.com/cover-large-2.jpg",
          "suno_model_name": "v5",
          "duration": 118.2,
          "created_at": 1773969602219
        }
      ]
    },
    "credits": 12,
    "duration_s": 137,
    "complete_at": 1768900515,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "failed",
    "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": {
      "code": 501,
      "message": "generation failed"
    },
    "credits": 0,
    "duration_s": 137,
    "complete_at": 1768900515,
    "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"

import requests

API_KEY = "YOUR_API_KEY"

headers = {
  "X-API-KEY": API_KEY,
  "Content-Type": "application/json"
}
params = {
  "task_id": "task_12345678",
}

GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

response = requests.get(GET_TASK_STATUS_URL, params=params, headers=headers)
print(response.json())

const API_KEY = "YOUR_API_KEY";
const taskId = "task_12345678";

const url = new URL("https://api.crun.ai/api/v1/client/job/TaskInfo");
url.searchParams.append("task_id", taskId);

fetch(url.toString(), {
  method: "GET",
  headers: {
      "X-API-KEY": API_KEY,
      "Content-Type": "application/json",
  },
})
  .then(res => res.json())
  .then(data => {
      console.log(data);
  })
  .catch(err => {
      console.error("请求失败:", err);
  });

{
  "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,
    "credits": 12,
    "duration_s": null,
    "complete_at": null,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "success",
    "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": {
      "code": 200,
      "message": "generation success",
      "suno_data": [
        {
          "suno_id": "suno_abc123",
          "title": "Midnight Addiction",
          "prompt": "[Verse 1] I still taste your words in the dark...",
          "tags": "Western R&B, female vocal, dark, sensual",
          "suno_audio_url": "https://example.com/audio.mp3",
          "suno_image_url": "https://example.com/cover.jpg",
          "suno_image_large_url": "https://example.com/cover-large.jpg",
          "suno_model_name": "v5",
          "duration": 123.45,
          "created_at": 1773969602219
        },
        {
          "suno_id": "suno_def456",
          "title": "Neon Dreams",
          "prompt": "Lo-fi chill instrumental hip hop beat...",
          "tags": "lofi, chill, instrumental",
          "suno_audio_url": "https://example.com/audio-2.mp3",
          "suno_image_url": "https://example.com/cover-2.jpg",
          "suno_image_large_url": "https://example.com/cover-large-2.jpg",
          "suno_model_name": "v5",
          "duration": 118.2,
          "created_at": 1773969602219
        }
      ]
    },
    "credits": 12,
    "duration_s": 137,
    "complete_at": 1768900515,
    "source": "api"
  }
}

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
    "provider": "Suno",
    "model_version": "sunov5",
    "status": "failed",
    "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": {
      "code": 501,
      "message": "generation failed"
    },
    "credits": 0,
    "duration_s": 137,
    "complete_at": 1768900515,
    "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 时返回。

credits

number

任务消耗的积分，任务状态是pending 或 running 时表示预扣积分，任务状态是 success 或 failed 时表示实际消耗积分。

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参考

Suno任务

Suno API 任务信息

API 接口

查询参数

请求示例

响应格式

SunoMusicItem 对象

任务状态枚举

获取任务结果最佳实践

常见错误码

速率限制

相关资源

Suno 快速开始

生成音乐

扩展音乐

音乐翻唱

授权

查询参数

响应

​API 接口

​查询参数

​请求示例

​响应格式

​SunoMusicItem 对象

​任务状态枚举

​获取任务结果最佳实践

​常见错误码

​速率限制

​相关资源

Suno 快速开始

生成音乐

扩展音乐

音乐翻唱

授权

查询参数

响应

API 接口

查询参数

请求示例

响应格式

SunoMusicItem 对象

任务状态枚举

获取任务结果最佳实践

常见错误码

速率限制

相关资源