Panorama de la documentación de Suno API

Actualizado el 2026-09-18 · equipo de Suno-API

Basta con registrarse con un correo electrónico para crear una clave de API. Cada generación cuesta 0,6 ¥ y devuelve 2 canciones, con descarga en MP3/WAV, covers, Extend, separación de pistas y clonación de voz. URL base: https://www.suno-api.io.

Esta página presenta los modelos disponibles, todos los endpoints de generación y edición, la facturación y el orden de lectura recomendado. Si es tu primera integración, léela de arriba abajo; las rutas de diagnóstico de 401/403/429 también están aquí.

Respuestas rápidas

¿Cómo consigo una clave de API? Regístrate con un correo, entra en la consola, ve a gestión de tokens y crea un token. No hace falta teléfono ni tarjeta.

¿Cuánto cuesta cada llamada? Una generación cuesta 0,6 ¥ y devuelve 2 canciones. Las consultas de estado, el WAV, las letras con marcas de tiempo y las sugerencias de prompt no tienen coste adicional.

¿Qué modelos se admiten? suno-v6 (predeterminado), suno-v6-wild y suno-v6-mini. Los modelos de generación estándar v5.5 y anteriores están retirados; los trabajos existentes no se ven afectados.

¿Cuál es la URL base? https://www.suno-api.io, con la cabecera Authorization: Bearer YOUR_API_KEY.

Modelos disponibles actualmente

Los modelos que el cliente puede indicar en la generación estándar son suno-v6, suno-v6-wild y suno-v6-mini. Si se omite model, se usa suno-v6.

Los modelos estándar suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 y suno-v5-5 están retirados. En tareas históricas pueden aparecer esos nombres, pero son solo datos históricos y no significan que el modelo siga disponible para nuevas peticiones. La separación de pistas es la excepción: consulta la API de separación (voz/acompañamiento).

Autenticación

Todos los endpoints públicos con clave de API usan las mismas cabeceras:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL base:

https://www.suno-api.io

Convenciones generales de parámetros

• Un number en el cuerpo debe ser un número JSON, nunca un porcentaje en texto. Una intensidad del 50 % se escribe 0.5, nunca 50 ni 50%.
• Un boolean debe ser true o false. No envíes true, false, 0 o 1 como sustitutos.
• Los campos marcados como «no» pueden omitirse por completo. Si dudas de un parámetro, omítelo y deja que el servicio use su comportamiento predeterminado; no envíes cadena vacía, null o 0 en lugar de «no enviado», porque 0 es un valor válido en algunos campos numéricos.
• Los nombres de campo distinguen la ortografía. Cada página indica el campo recomendado y los alias compatibles; envíalos tal como aparecen en la tabla. Donde la documentación dice que snake_case y camelCase son válidos, no envíes ambos a la vez.
• Todos los campos de duración terminados en _s o Seconds están en segundos y admiten decimales. Las marcas de tiempo Unix se describen aparte, indicando si son segundos o milisegundos.
• Un identificador que empieza por pending: es un marcador de posición de la plataforma, no un ID real de canción. Úsalo solo donde el endpoint lo documente explícitamente; si no, espera al song_id real.

Límites de los campos de texto

Superar un límite devuelve HTTP 400 directamente: no se genera nada, no se pre-cobra nada y no se crea ningún registro de tarea. El recuento es por caracteres Unicode (un ideograma cuenta como 1) y los espacios iniciales y finales también cuentan.

El message de error indica el campo afectado y la longitud medida, así que esos dos números bastan para recortar el texto:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Se aplica a: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Una excepción: el campo description de POST /api/music/sounds está limitado a 100 caracteres, porque la ruta de efectos de sonido usa el límite más corto de la plataforma.

Generación asíncrona y direcciones de audio

Los endpoints de generación musical funcionan de forma asíncrona por defecto. Cuando la primera respuesta trae status igual a pending, submitted o processing, que audio_url, video_url o cover_url estén vacíos es normal y no significa que la tarea haya fallado. Guarda el song_id real (o el client_request_id devuelto) y consulta el endpoint correspondiente; solo lee y descarga una dirección de audio cuando el estado esté completado.

⚠️ Las direcciones de audio caducan a los 7 días: transfiere los archivos a tiempo

audio_url, wav_url, video_url y las direcciones que devuelven los endpoints de descarga se sirven desde el almacenamiento de objetos de la plataforma y caducan por defecto a los 7 días (los archivos se reciclan; una dirección antigua devuelve 404 / no descarga).

• Dentro de esos 7 días, copia los archivos a tu propio almacenamiento (tu almacenamiento de objetos, una CDN o un disco de servidor). No trates nuestras direcciones como enlaces permanentes.
• Una dirección caducada no obliga a regenerar la canción y no cuesta nada extra: vuelve a llamar a la API de consulta de canciones (o a la API de descarga de medios) para obtener una dirección nueva y válida.

Tiempos de espera y configuración de timeout

Los endpoints de generación son síncronos: el pedido solo se acepta y se entrega a la plataforma cuando llega la respuesta. Antes de eso, el servicio debe programar una cuenta y superar la comprobación de seguridad necesaria, y no hay respuesta intermedia: ningún otro endpoint ve el pedido. Por tanto, la única prueba fiable de que «se generó algo» es la propia respuesta, no lo que se observe mientras se espera.

Tiempos medidos (producción, familia /api/music/create, del 18 al 20 de septiembre de 2026)

• Alrededor del 10 % de las peticiones tardan más de 30 segundos y cerca del 1 % entre 1 y 2 minutos. Una petición lenta suele significar que esta vez hubo que pasar primero una comprobación de seguridad.
• Los campos, la forma de la respuesta, los códigos de error y la facturación no cambian, así que las integraciones existentes solo necesitan subir el timeout del cliente, sin tocar nada más.

Requisitos de integración

1. Configura el timeout del cliente en 300 segundos o más. Los clientes con 30, 60 o 120 segundos por defecto cortan la conexión durante la espera.
2. No recibir respuesta no significa que no se haya generado nada. Con un timeout o una conexión cortada, el pedido puede estar ya aceptado y generándose.
3. No reintentes inmediatamente tras un timeout: un envío duplicado crea un segundo pedido y vuelve a cobrar.
4. Si la conexión se cortó, lista tus canciones con GET /api/music/songs (más recientes primero) un poco después: los pedidos aceptados aparecen con normalidad. Reenvía solo tras confirmar que el pedido no existe.
5. Al reportar un problema, incluye la cabecera de respuesta X-Oneapi-Request-Id para localizar exactamente esa petición.

¿Prefieres no mantener una conexión larga? Usa el modo de acuse de recibo. POST /api/music/create y POST /api/music/create/custom admiten un acuse opcional: añade "accept_mode": "async" al cuerpo (o la cabecera X-Accept-Mode: async) y el endpoint devuelve 202 de inmediato con un número de acuse mientras la generación continúa en segundo plano; consulta el progreso con GET /api/music/requests/{request_id}. Un cliente con solo unas decenas de segundos de timeout ya no puede confundir «sin respuesta» con «nada generado», ni cobrar dos veces por reintentos. Ver «Modo de acuse de recibo» en la API de generación en modo simple.

Como referencia: python requests usa timeout=300, urllib usa urlopen(..., timeout=300), Node usa req.setTimeout(300000), curl usa --max-time 300.

Lista de endpoints recomendados

Los endpoints /api/voice/clone/* y /api/music/generate-with-voice pertenecen a la cadena inicial de clonación de voz y no se recomiendan para nuevas integraciones; usa mejor la 【Recomendado】 API de perfil de voz.

Parámetros avanzados: Max Mode y Variety

Los endpoints de generación admiten estos dos parámetros opcionales (omitirlos mantiene el comportamiento y el precio anteriores):

Endpoints que los admiten: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• El doble de precio en la práctica: un endpoint de 0,6 ¥ por llamada pasa a 1,2 ¥ con max_mode; generar con una voz elegida cuesta 1,2 ¥ por llamada y 2,4 ¥ con Max Mode; el cover de voz de la 【Recomendado】 API de perfil de voz también cuesta 1,2 ¥ por llamada (2,4 ¥ con max_mode).
• variety solo se aplica a la familia suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); enviarlo con otro modelo devuelve 400.
• Los efectos de sonido, la separación de pistas, el concat, el WAV y las acciones de edición de Studio (recorte, quitar sección, fundido, invertir, velocidad, etc.) no aceptan estos parámetros: enviarlos explícitamente devuelve 400, para que ningún parámetro se ignore en silencio.
• variety es el entero 0-4; style_weight y weirdness_constraint son decimales de 0 a 1, así que las escalas son distintas.

Campos de respuesta comunes de las canciones

Los endpoints de generación, cover, extend, separación y consulta suelen devolver un array de canciones con estos campos:

Cuatro pasos para integrar (ejemplo mínimo)

Con estos cuatro pasos obtienes tu primera canción; la lista completa de campos de cada paso está en la página correspondiente de la lista de endpoints recomendados.

# 1) Enviar una generación: 0,6 ¥, devuelve 2 canciones
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Spanish pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Consultar hasta que status sea completed (3-5 segundos es un buen intervalo)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "el song_id devuelto en el paso 1"}'

# 3) Obtener una dirección de medios: los endpoints de lectura son gratis; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "el mismo song_id", "kind": "song"}'

Si algo falla: 401 / 402 / 403 / 429 están en la guía de errores; timeouts y cobros duplicados en la sección «Tiempos de espera y configuración de timeout»; el detalle de cada endpoint en la lista de abajo.

Recomendaciones

• Las integraciones nuevas deberían usar suno-v6 en todas las llamadas.
• En los endpoints que indican un precio predeterminado, el importe real sigue la configuración de precios del back office y el modelo solicitado.
• Los endpoints de generación devuelven primero una tarea; obtén el audio final con /api/music/query.
• wait_completion=true bloquea hasta terminar y sirve para pruebas de bajo volumen; en producción es preferible consultar de forma asíncrona.
• Los endpoints de generación pueden tardar bastante en responder: configura el timeout del cliente en 300 segundos o más y recuerda que «sin respuesta» no es lo mismo que «nada generado».
• Las capacidades de subida, cover, reemplazo y WAV dependen de las cuentas de la plataforma y de los permisos del clip de origen; cuando fallen, lee primero el message o el error_message devuelto.

Sobre esta documentación

Esta página se reorganizó en torno a las capacidades que la Create UI expone realmente, y las integraciones nuevas deberían leerla primero. La documentación antigua de la API sigue disponible en la sección «Documentación antigua de la API (compatible)» para quien prefiera su método anterior.