Convenciones generales de Suno y consulta de tareas

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}

Convenciones generales de Suno y consulta de tareas

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 contiene las convenciones comunes de todas las interfaces de música Suno y se usa junto con la documentación individual de cada endpoint. Todas las interfaces de generación / edición son tareas asíncronas: al enviar se obtiene un task_id, y luego se sondea la interfaz de consulta de esta página para obtener el resultado.

Autenticación

Todas las solicitudes deben incluir en los encabezados:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Visita la página de gestión de API Key para obtener tu API Key.

Ciclo de vida de la tarea (todas las interfaces son asíncronas)

Enviar

POST /v1/music/generations/<operación> → devuelve de inmediato nuestro task_id:

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

Sondear

GET /v1/music/tasks/:task_id hasta que status sea completed o failed. Durante la generación, status es pending y progress avanza en cola 10 → listo 50 → hecho 100. Se recomienda un intervalo de sondeo de 3–5s; la generación de música suele tardar 30–120s.

Obtener el resultado

Al completarse, obtén audio_url / image_url / video_url, etc. desde data.result.music[].

Flujo de estados de la tarea: submitted → pending → completed / failed. En caso de fallo, data.error.message indica el motivo y el saldo retenido previamente se reembolsa automáticamente.

Versión

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, afecta la calidad del audio y la facturación; si no se pasa, se usa el valor por defecto. La disponibilidad y los valores por defecto varían según el endpoint: algunos solo admiten un subconjunto y otros no tienen dimensión de versión en absoluto; consulta la documentación de cada endpoint.

Referenciar la pista de audio de origen: task_id + audio_index

Las operaciones basadas en una canción existente (continuar / versionar / separar pistas / añadir voces / recortar…) no requieren recordar ningún id ascendente, solo se pasa:

task_id: nuestro task_id de la tarea que produjo la pista de audio de origen
audio_index: qué canción del resultado music[] de esa tarea (basado en 1, por defecto 1; una generación suele producir 2 canciones: 1 y 2)

Si no se puede resolver el origen (tarea no completada / índice fuera de rango / task_id inexistente), se devuelve un 400 en el momento del envío.

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

task_id

string

requerido

Nuestro task_id devuelto por la interfaz de envío.

Sondea esta interfaz hasta que status sea completed o failed. Tras completarse, obtén los productos desde data.result.music[].

Response

task_id

string

Identificador único de la tarea

status

string

Estado de la tarea: submitted / pending / completed / failed

progress

integer

Progreso: en cola 10 → listo 50 → hecho 100

data

object

Datos del resultado

Mostrar Propiedades

result

object

Presente cuando status es completed

Mostrar Propiedades de result

music

array

Lista de productos (una generación suele producir 2 canciones)

Mostrar Propiedades de music[]

audio_id

string

id de la pista de audio, para localizar mediante audio_index en operaciones posteriores

title

string

Título

duration

number

Duración (segundos)

lyrics

string

Letra

Visión general

Serie de texto

Serie de imágenes

Serie de video

Serie de audio

Serie de Moderación

Gestión de subidas

Gestión de tareas

Gestión de cuenta

Convenciones generales de Suno y consulta de tareas

Autenticación

Ciclo de vida de la tarea (todas las interfaces son asíncronas)

Versión

Referenciar la pista de audio de origen: task_id + audio_index

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

Response

​Autenticación

​Ciclo de vida de la tarea (todas las interfaces son asíncronas)

​Versión

​Referenciar la pista de audio de origen: task_id + audio_index

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

​Response

Autenticación

Ciclo de vida de la tarea (todas las interfaces son asíncronas)

Versión

Referenciar la pista de audio de origen: task_id + audio_index

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

Response