Suno 通用约定与任务查询

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', 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.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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.apimart.ai/v1/music/tasks/{task_id}"

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

	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.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

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

request = Net::HTTP::Get.new(url)

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

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<音轨id，供后续操作 audio_index 定位>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

GET

music

tasks

{task_id}

Suno 通用约定与任务查询

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', 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.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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.apimart.ai/v1/music/tasks/{task_id}"

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

	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.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

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

request = Net::HTTP::Get.new(url)

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

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<音轨id，供后续操作 audio_index 定位>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

本页是所有 Suno 音乐接口的公共约定，配合每个端点单独文档使用。所有生成 / 编辑接口均为异步任务：提交拿 task_id，再轮询本页的查询接口取结果。

认证

所有请求都需要在请求头中携带：

Authorization: Bearer <你的API Key>
Content-Type: application/json

访问 API Key 管理页面获取 API Key。

任务生命周期（所有接口均为异步）

提交

POST /v1/music/generations/<操作> → 立即返回我方 task_id：

{ "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }

轮询

GET /v1/music/tasks/:task_id 直到 status 为 completed 或 failed。生成中 status 为 pending，progress 排队 10 → 就绪 50 → 完成 100。建议轮询间隔 3–5s；音乐生成通常 30–120s。

取结果

完成后从 data.result.music[] 取 audio_url / image_url / video_url 等。

任务状态流转：submitted → pending → completed / failed。失败时 data.error.message 给出原因，且预扣额度自动退回。

版本 version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5，影响音质与计费；不传使用默认。各端点的可用版本与默认值不同——部分端点只支持子集，部分端点无版本维度；以各端点自身文档为准。

引用源音轨：task_id + audio_index

基于已有歌曲的操作（续写 / 翻唱 / 分轨 / 加人声 / 裁剪…）不需要记任何上游 id，只传：

task_id：产出源音轨那次任务的我方 task_id
audio_index：该任务结果 music[] 里第几首（1-based，默认 1；一次生成通常 2 首：1 和 2）

无法解析源时（任务未完成 / 序号越界 / task_id 不存在），提交期直接返回 400。

查询任务：GET /v1/music/tasks/:task_id

task_id

string

必填

提交接口返回的我方 task_id。

轮询该接口直到 status 为 completed 或 failed。完成后从 data.result.music[] 取产物。

Response

task_id

string

任务唯一标识符

status

string

任务状态：submitted / pending / completed / failed

progress

integer

进度：排队 10 → 就绪 50 → 完成 100

data

object

结果数据

显示属性

result

object

status 为 completed 时存在

显示 result 属性

music

array

产物列表（一次生成通常 2 首）

显示 music[] 属性

audio_id

string

音轨 id，供后续操作用 audio_index 定位

title

string

标题

duration

number

时长（秒）

lyrics

string

歌词

概览

文字系列

图像系列

视频系列

音频系列

审核系列

上传管理

任务管理

账户管理

Suno 通用约定与任务查询

认证

任务生命周期（所有接口均为异步）

版本 version

引用源音轨：task_id + audio_index

查询任务：GET /v1/music/tasks/:task_id

Response

​认证

​任务生命周期（所有接口均为异步）

​版本 version

​引用源音轨：task_id + audio_index

​查询任务：GET /v1/music/tasks/:task_id

​Response

认证

任务生命周期（所有接口均为异步）

版本 version

引用源音轨：task_id + audio_index

查询任务：GET /v1/music/tasks/:task_id

Response