AIGC API Service

Appearance

Suno 任务查询 ​

用于查询 Suno 异步任务结果。该接口不支持 async_mode，也不会触发新的生成任务。

接口地址 ​

http
POST /suno/tasks

请求参数 ​

参数类型必填默认值说明
actionstring是-查询动作：retrieve 或 batch_retrieve
idstring否-单个任务 ID
idsstring[]否-批量任务 ID

必须提供 id 或 ids。当 action 为 retrieve 时必须提供 id；当 action 为 batch_retrieve 时通常提供 ids。

请求示例 ​

json
{
  "action": "retrieve",
  "id": "your-task-id"
}

批量查询：

json
{
  "action": "batch_retrieve",
  "ids": ["task-id-1", "task-id-2"]
}

Python 示例 ​

python
import requests

url = "https://your-domain.com/suno/tasks"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "action": "retrieve",
    "id": "your-task-id",
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)

响应说明 ​

单个任务查询 ​

当 action 为 retrieve 且传入单个 id 时，接口返回任务记录对象。任务的原始请求在 request 字段中，Suno 返回结果在 response 字段中；生成成功后，歌曲列表通常位于 response.data。

常见字段如下：

字段说明
_id任务记录内部 ID
id任务 ID，与请求中的 id 对应
api_idAPI 调用 ID
application_id应用 ID
created_at任务创建时间戳
credential_id使用的凭证 ID
request创建任务时的原始请求参数
request.action原始任务动作，例如 generate
request.model使用的 Suno 模型
request.custom是否使用自定义模式
request.instrumental是否生成纯音乐
request.style歌曲风格
request.lyric自定义歌词
trace_id请求追踪 ID，排查问题时可一并提供
type任务类型，例如 audios
user_id用户 ID
job_id上游任务 ID
response.success上游任务是否成功
response.task_id上游任务 ID
response.trace_id上游请求追踪 ID
response.data生成结果列表
response.data[].id歌曲 ID，可用于续写、视频、WAV、SRT 等后续接口
response.data[].title歌曲标题
response.data[].image_url歌曲封面图片 URL
response.data[].lyric歌词
response.data[].audio_url歌曲音频文件 URL，通常为 MP3
response.data[].video_url歌曲视频文件 URL；为空表示当前未生成视频
response.data[].created_at歌曲创建时间
response.data[].model使用的模型
response.data[].state任务状态，成功时通常为 succeeded
response.data[].prompt生成提示词；自定义歌词生成时可能为 null
response.data[].style歌曲风格
response.data[].display_style展示风格
response.data[].duration歌曲时长，单位为秒

响应示例：

json
{
  "_id": "6a130b17b72904f939e2c31f",
  "id": "b7eecc63-7bb8-4af9-8699-6c5212549b03",
  "api_id": "dc2df3b3-a9ad-462b-b61c-1e9ee536196d",
  "application_id": "2b75bd58-96b6-4460-9f8a-1360e78ee71b",
  "created_at": 1779632919.97,
  "credential_id": "d992bec1-5b17-40a6-ab18-b6298ef89b52",
  "request": {
    "action": "generate",
    "model": "chirp-v4",
    "custom": true,
    "instrumental": false,
    "style": "indie pop, warm, emotional, female vocal",
    "lyric": "[Verse 1]\nThe city lights are fading slow\n...\nEvening wind passes me"
  },
  "trace_id": "b50fcaf9-15e7-44de-b883-7fc8f420441e",
  "type": "audios",
  "user_id": "ad963978-27cb-4c02-9457-b91c79c34f00",
  "job_id": 81845642,
  "response": {
    "success": true,
    "task_id": "b7eecc63-7bb8-4af9-8699-6c5212549b03",
    "trace_id": "b50fcaf9-15e7-44de-b883-7fc8f420441e",
    "data": [
      {
        "id": "8c15f6ef-fa85-4f86-b8f7-488ed32bae9a",
        "title": "Evening Wind Melody",
        "image_url": "https://cdn2.suno.ai/image_8c15f6ef-fa85-4f86-b8f7-488ed32bae9a.jpeg",
        "lyric": "[Verse 1]\nThe city lights are fading slow\n...",
        "audio_url": "https://cdn1.suno.ai/8c15f6ef-fa85-4f86-b8f7-488ed32bae9a.mp3",
        "video_url": "",
        "created_at": "2026-05-24T14:28:53.527Z",
        "model": "chirp-v4",
        "state": "succeeded",
        "prompt": null,
        "style": "indie pop, warm, emotional, female vocal",
        "display_style": "",
        "duration": 194.92
      },
      {
        "id": "ef4c3d69-55f1-4512-b5fd-a6a7018e2788",
        "title": "Evening Wind Melody",
        "image_url": "https://cdn2.suno.ai/image_ef4c3d69-55f1-4512-b5fd-a6a7018e2788.jpeg",
        "lyric": "[Verse 1]\nThe city lights are fading slow\n...",
        "audio_url": "https://cdn1.suno.ai/ef4c3d69-55f1-4512-b5fd-a6a7018e2788.mp3",
        "video_url": "",
        "created_at": "2026-05-24T14:28:53.527Z",
        "model": "chirp-v4",
        "state": "succeeded",
        "prompt": null,
        "style": "indie pop, warm, emotional, female vocal",
        "display_style": "",
        "duration": 240
      }
    ]
  }
}

最终响应字段以接口实际返回为准；不同任务类型或失败状态下，response 的内容可能不同。

扣费说明 ​

任务查询不配置独立扣费。