curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Error de autenticación. Comprueba tu clave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo de la cuenta insuficiente",
"type": "payment_required"
}
}
Suno
Descargar archivos de audio
- Descarga canciones de Suno como archivos MP3, M4A o WAV
- Solicita varios formatos a la vez y recibe una URL para cada archivo
- Selecciona la canción de origen con task_id y audio_index
- Envía la solicitud de forma asíncrona y consulta el resultado en el endpoint de tareas de música
POST
/
v1
/
music
/
generations
/
download
curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Error de autenticación. Comprueba tu clave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo de la cuenta insuficiente",
"type": "payment_required"
}
}
El endpoint anterior
POST /v1/music/generations/wav está obsoleto. Sigue siendo compatible temporalmente y equivale al nuevo endpoint con formats: ["wav"]. Las integraciones nuevas deben usar POST /v1/music/generations/download.Selecciona la canción de origen: envía el
task_id de la tarea que creó el audio de origen y usa audio_index para elegir una pista del resultado music[]. El índice comienza en 1 y su valor predeterminado es 1.curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Error de autenticación. Comprueba tu clave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo de la cuenta insuficiente",
"type": "payment_required"
}
}
Autenticación
string
requerido
Todas las API requieren autenticación mediante Bearer Token. Obtén tu clave en la página de claves de API.
Authorization: Bearer YOUR_API_KEY
Parámetros de solicitud
string
predeterminado:"suno"
Nombre del modelo. Usa
suno; si se omite, el valor predeterminado también es suno.string
requerido
ID de la tarea que creó la canción de origen.La tarea de origen debe pertenecer a la cuenta actual, estar completada y contener audio descargable. Se admiten tareas de generación, extensión, cover y stems; no se admiten tareas que solo generan texto, como letras o análisis de BPM.
integer
predeterminado:"1"
Número de pista dentro del resultado
music[] de la tarea de origen.- El índice comienza en
1 - Valor predeterminado:
1 - No puede superar el número de pistas de la tarea de origen
string[]
Array de formatos solicitados con al menos un elemento.Valores admitidos:
mp3, m4a, wav.Puedes solicitar varios formatos a la vez. No se distinguen mayúsculas y minúsculas, los duplicados se eliminan automáticamente y el orden del resultado coincide con el de la solicitud.string
Para un solo formato, este campo puede sustituir a
formats.Ejemplo: "format": "mp3"Usa
formats o format. Si omites ambos o envías un array vacío, la API devuelve HTTP 400.Respuesta del envío
Un envío correcto devuelve un nuevotask_id para la tarea de descarga.
data es un array; lee data[0].task_id. Este ID pertenece a la nueva tarea de descarga y es distinto del task_id de la canción de origen enviado en la solicitud.Consultar el resultado de descarga
Usa el ID de la tarea de descarga:GET /v1/music/tasks/{task_id}
completed ni failed, consulta cada 2 segundos durante un máximo de 60 segundos.
Completado
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "completed",
"progress": 100,
"cost": 0.01,
"credits_cost": 0.1,
"result": {
"music_id": "518c74ee-62ac-4ccd-b3d9-7003acd12ad7",
"files": [
{
"format": "mp3",
"url": "https://assets.apimart.ai/audio/example.mp3"
},
{
"format": "wav",
"url": "https://assets.apimart.ai/audio/example.wav"
}
],
"wavUrl": "https://assets.apimart.ai/audio/example.wav"
}
}
}
result.files[] para obtener los archivos:
| Campo | Tipo | Descripción |
|---|---|---|
format | string | mp3 / m4a / wav |
url | string | URL de descarga del archivo |
result.wavUrl solo existe por compatibilidad con la API WAV anterior. El código nuevo debe leer siempre result.files[].En proceso
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "processing",
"progress": 50,
"created": 1756800000
}
}
result. Continúa consultando.
Fallido
Las tareas fallidas se reembolsan automáticamente y devuelvencost: 0. Muestra error.message y permite volver a intentarlo.
URL de los archivos
Los resultados normalmente usan el dominio de archivos de APIMart. Si falla la transferencia al almacenamiento, puede devolverse una URL de la CDN del proveedor sin garantía de vigencia.Descarga y guarda el archivo cuanto antes. No uses una URL temporal como almacenamiento permanente.
Errores
Los errores de validación devuelven HTTP 400 antes de crear la tarea y aplicar el cobro.| Texto del error | Motivo |
|---|---|
formats is required / must contain at least one | Falta el formato |
unsupported format | Valor distinto de mp3 / m4a / wav |
task_id is required / invalid task_id format | Falta el ID de la tarea o no es válido |
source task not found | La tarea no existe o pertenece a otra cuenta |
audio_index N out of range | El número de pista está fuera del intervalo |
track #N has no music_id | La tarea no está completa o la pista no contiene audio |
model_price_not_configured significa que el precio suno@download no está configurado; contacta con soporte.
Facturación y descargas repetidas
- Una solicitud con varios formatos genera un solo cobro
- Volver a enviar la misma canción genera otro cobro, incluso para el mismo formato
- Solicitar otro formato en una tarea posterior también genera otro cobro
- Las tareas fallidas se reembolsan automáticamente
Reutiliza las URL ya recibidas y desactiva el botón de descarga mientras haya una solicitud en curso para evitar envíos y cobros duplicados.
Migración desde la API anterior
| Elemento | Anterior | Actual |
|---|---|---|
| Ruta | /v1/music/generations/wav | /v1/music/generations/download |
| Formatos | Solo WAV | MP3 / M4A / WAV; admite varios |
| Parámetro | — | formats o format |
| Resultado | result.wavUrl | result.files[] |
/generations/download.
Response
integer
Código de respuesta; 200 si la solicitud se completa correctamente