Skip to main content
POST
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.

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.

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 nuevo task_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:
Los archivos normalmente se preparan durante el envío. Consulta una vez de inmediato; si el estado no es completed ni failed, consulta cada 2 segundos durante un máximo de 60 segundos.

Completado

Lee result.files[] para obtener los archivos:
result.wavUrl solo existe por compatibilidad con la API WAV anterior. El código nuevo debe leer siempre result.files[].

En proceso

Todavía no hay result. Continúa consultando.

Fallido

Las tareas fallidas se reembolsan automáticamente y devuelven cost: 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. HTTP 403 con 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

La API anterior sigue disponible temporalmente, pero todo el código nuevo debe usar /generations/download.

Response

integer
Código de respuesta; 200 si la solicitud se completa correctamente
array
Datos de la respuesta del envío