Suno Common Conventions & Task Query

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": "<track id, used with audio_index to locate it for subsequent operations>",
          "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 Common Conventions & Task Query

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": "<track id, used with audio_index to locate it for subsequent operations>",
          "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"
    }
  }
}

This page covers the common conventions shared by all Suno music APIs and is meant to be used alongside the individual documentation for each endpoint. All generation / editing APIs are asynchronous tasks: submit to get a task_id, then poll the query API on this page to retrieve results.

Authentication

All requests must include the following in the request headers:

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

Visit the API Key management page to obtain an API Key.

Task Lifecycle (all APIs are asynchronous)

Submit

POST /v1/music/generations/<operation> → immediately returns our task_id:

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

Poll

GET /v1/music/tasks/:task_id until status is completed or failed. While generating, status is pending and progress goes queued 10 → ready 50 → done 100. A polling interval of 3–5s is recommended; music generation usually takes 30–120s.

Retrieve results

On completion, take audio_url / image_url / video_url, etc. from data.result.music[].

Task status transitions: submitted → pending → completed / failed. On failure, data.error.message gives the reason and the pre-deducted quota is automatically refunded.

Version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, affecting audio quality and billing; the default is used if omitted. Availability and defaults vary per endpoint — some support only a subset, and some have no version dimension at all; see each endpoint’s own documentation.

Referencing a Source Track: task_id + audio_index

Operations based on an existing song (extend / cover / stem separation / add vocals / trim…) do not require you to remember any upstream id; you only pass:

task_id: our task_id for the task that produced the source track
audio_index: which track in that task’s result music[] (1-based, defaults to 1; a single generation usually produces 2 tracks: 1 and 2)

If the source cannot be resolved (task not complete / index out of range / task_id not found), a 400 is returned at submission time.

Query Task: GET /v1/music/tasks/:task_id

task_id

string

required

Our task_id returned by the submit API.

Poll this API until status is completed or failed. Once completed, retrieve the products from data.result.music[].

Response

task_id

string

Unique task identifier

status

string

Task status: submitted / pending / completed / failed

progress

integer

Progress: queued 10 → ready 50 → done 100

data

object

Result data

Show Properties

result

object

Present when status is completed

Show result properties

music

array

List of products (a single generation usually produces 2 tracks)

Show music[] properties

audio_id

string

Track id, used with audio_index to locate it for subsequent operations

title

string

Title

duration

number

Duration (seconds)

lyrics

string

Lyrics

Overview

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

Suno Common Conventions & Task Query

Authentication

Task Lifecycle (all APIs are asynchronous)

Version

Referencing a Source Track: task_id + audio_index

Query Task: GET /v1/music/tasks/:task_id

Response

​Authentication

​Task Lifecycle (all APIs are asynchronous)

​Version

​Referencing a Source Track: task_id + audio_index

​Query Task: GET /v1/music/tasks/:task_id

​Response

Authentication

Task Lifecycle (all APIs are asynchronous)

Version

Referencing a Source Track: task_id + audio_index

Query Task: GET /v1/music/tasks/:task_id

Response