Convenções Gerais e Consulta de Tarefas do 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": "<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}

Convenções Gerais e Consulta de Tarefas do 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": "<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"
    }
  }
}

Esta página contém as convenções comuns de todas as interfaces de música do Suno, usada em conjunto com a documentação individual de cada endpoint. Todas as interfaces de geração / edição são tarefas assíncronas: envie para obter o task_id e, em seguida, faça polling na interface de consulta desta página para obter o resultado.

Autenticação

Todas as requisições precisam incluir no cabeçalho:

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

Acesse a página de gerenciamento de API Key para obter sua API Key.

Ciclo de vida da tarefa (todas as interfaces são assíncronas)

Enviar

POST /v1/music/generations/<operação> → retorna imediatamente o nosso task_id:

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

Fazer polling

GET /v1/music/tasks/:task_id até que status seja completed ou failed. Durante a geração, status é pending e progress vai de na fila 10 → pronto 50 → concluído 100. Recomenda-se um intervalo de polling de 3–5s; a geração de música normalmente leva 30–120s.

Obter resultado

Após a conclusão, obtenha audio_url / image_url / video_url, etc. de data.result.music[].

Fluxo de estados da tarefa: submitted → pending → completed / failed. Em caso de falha, data.error.message informa o motivo e a cota pré-reservada é devolvida automaticamente.

Versão version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, afeta a qualidade do áudio e a cobrança; se não for informado, usa-se o padrão. A disponibilidade e os valores padrão variam conforme o endpoint — alguns suportam apenas um subconjunto e outros não têm dimensão de versão; consulte a documentação de cada endpoint.

Referência à faixa de origem: task_id + audio_index

Operações baseadas em músicas já existentes (continuação / cover / separação de faixas / adição de vocais / recorte…) não exigem que você guarde nenhum id upstream, basta informar:

task_id: o nosso task_id da tarefa que produziu a faixa de origem
audio_index: qual faixa dentro do music[] do resultado dessa tarefa (baseado em 1, padrão 1; uma geração normalmente produz 2 músicas: 1 e 2)

Se a origem não puder ser resolvida (tarefa não concluída / índice fora do intervalo / task_id inexistente), um 400 é retornado no momento do envio.

Consultar tarefa: GET /v1/music/tasks/:task_id

task_id

string

obrigatório

O nosso task_id retornado pela interface de envio.

Faça polling nessa interface até que status seja completed ou failed. Após a conclusão, obtenha os produtos de data.result.music[].

Response

task_id

string

Identificador único da tarefa

status

string

Estado da tarefa: submitted / pending / completed / failed

progress

integer

Progresso: na fila 10 → pronto 50 → concluído 100

data

object

Dados do resultado

Mostrar Propriedades

result

object

Presente quando status é completed

Mostrar Propriedades de result

music

array

Lista de produtos (uma geração normalmente produz 2 músicas)

Mostrar Propriedades de music[]

audio_id

string

id da faixa, usado para localizar em operações posteriores com audio_index

title

string

Título

duration

number

Duração (segundos)

lyrics

string

Letra

Visão Geral

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Convenções Gerais e Consulta de Tarefas do Suno

Autenticação

Ciclo de vida da tarefa (todas as interfaces são assíncronas)

Versão version

Referência à faixa de origem: task_id + audio_index

Consultar tarefa: GET /v1/music/tasks/:task_id

Response

​Autenticação

​Ciclo de vida da tarefa (todas as interfaces são assíncronas)

​Versão version

​Referência à faixa de origem: task_id + audio_index

​Consultar tarefa: GET /v1/music/tasks/:task_id

​Response

Autenticação

Ciclo de vida da tarefa (todas as interfaces são assíncronas)

Versão version

Referência à faixa de origem: task_id + audio_index

Consultar tarefa: GET /v1/music/tasks/:task_id

Response