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"
}
}
}
Suno
Convenciones generales de Suno y consulta de tareas
- Notas comunes de la API de música Suno: autenticación, ciclo de vida de las tareas asíncronas, model / version, referencia a la pista de audio de origen
- Consulta de tareas: GET /v1/music/tasks/:task_id, sondear hasta completed / failed
GET
/
v1
/
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
Ciclo de vida de la tarea (todas las interfaces son asíncronas)
1
Enviar
POST /v1/music/generations/<operación> → devuelve de inmediato nuestro task_id:{ "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }
2
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.3
Obtener el resultado
Al completarse, obtén
audio_url / image_url / video_url, etc. desde data.result.music[].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: nuestrotask_idde la tarea que produjo la pista de audio de origenaudio_index: qué canción del resultadomusic[]de esa tarea (basado en 1, por defecto1; 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
string
requerido
Nuestro
task_id devuelto por la interfaz de envío.status sea completed o failed. Tras completarse, obtén los productos desde data.result.music[].
Response
string
Identificador único de la tarea
string
Estado de la tarea:
submitted / pending / completed / failedinteger
Progreso: en cola
10 → listo 50 → hecho 100object
Datos del resultado
Mostrar Propiedades
Mostrar Propiedades
object
Presente cuando
status es completedMostrar Propiedades de result
Mostrar Propiedades de result
array
Lista de productos (una generación suele producir 2 canciones)
Mostrar Propiedades de music[]
Mostrar Propiedades de music[]
string
id de la pista de audio, para localizar mediante
audio_index en operaciones posterioresstring
Título
number
Duración (segundos)
string
Letra
string
Etiquetas de estilo
string
URL del archivo de audio
string
URL de la imagen de portada
string
URL de la portada en tamaño grande
string
URL del video MV (si ya se ha generado)
{
"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"
}
}
}