API de generación en modo personalizado

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

Descripción del endpoint

El modo personalizado sirve para cuando ya tienes letra, estilo y título listos y quieres controlar la voz que canta, la fuerza con que se sigue el estilo y el grado de aleatoriedad de la generación.

Endpoint: POST /api/music/create/custom

Facturación: De pago, actualmente 0,6 ¥ por llamada por defecto. Cada llamada suele devolver 2 canciones; el importe realmente cobrado sigue la configuración de precios actual del back-office.

Max Mode / Variety: este endpoint admite los parámetros opcionales max_mode y variety (0-4). Con max_mode activado, esta llamada se factura al doble (0,6 → 1,2 ¥ por llamada); variety no cuesta nada extra. Qué significan y cómo enviarlos está en la sección «Parámetros avanzados» del Resumen de la nueva API.

Tiempos de espera y timeouts (importante): es un endpoint síncrono — el pedido solo se acepta y se entrega a generación cuando llega la respuesta. Según lo medido, la mayoría de las peticiones responden en 1-3 segundos, alrededor del 10% tardan más de 30 segundos y la más lenta ronda los 230 segundos. Configura el timeout del cliente en 300 segundos o más; no recibir respuesta no significa que no se haya generado nada, y no reintentes justo después de un timeout (eso duplica el pedido y vuelve a cobrar). Si la conexión se cayó, confírmalo más tarde con GET /api/music/songs. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Parámetros de la petición

Headers

Parámetros del body

Notas sobre los parámetros avanzados

Género de la voz vocal_gender

• Envía m o male para voz masculina, f o female para voz femenina.
• El servicio normaliza male y female a m y f respectivamente.
• Con instrumental=true no se envía ningún parámetro de género de voz al servicio de generación.

Influencia del estilo style_weight

Controla con qué fuerza el resultado sigue style_tags. Cuanto más alto, más tiende el resultado a seguir las etiquetas que enviaste.

Aleatoriedad weirdness_constraint

Controla cuánto varía y experimenta el resultado. Valores altos suelen dar más variación; valores bajos suelen dar un resultado más seguro.

Ambos parámetros numéricos van de 0.0 a 1.0, y 0 es un valor explícito válido. Solo omitir el campo por completo significa «no especificado».

Al rellenarlos, ten en cuenta que son fracciones decimales, no enteros de porcentaje. Referencia sugerida: de 0.0 a 0.3 es conservador, de 0.4 a 0.6 es equilibrado, de 0.7 a 1.0 es más experimental; si no tienes preferencia clara usa 0.5 o simplemente omítelos. Ejemplo: weirdness_constraint: 0.5, nunca 50 ni 50%.

Con instrumental=true el resultado es instrumental, así que la letra y el género de la voz no actúan como en una canción cantada; si necesitas voz, envía false u omite el campo. Los campos booleanos deben usar true/false de JSON, no cadenas.

Ejemplo de petición en Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nLa noche cae sobre el mar\nuna brisa pasa junto a la ventana',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Brisa de la tarde junto al mar',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Modo de recibo de aceptación (opcional)

Este endpoint también admite el modo de recibo de aceptación de la API de generación en modo simple: con "accept_mode": "async" en el body (o la cabecera X-Accept-Mode: async), el endpoint devuelve 202 y un número de recibo de inmediato, la generación continúa en segundo plano, y sigues el progreso con GET /api/music/requests/{request_id}.

Encaja con clientes que no deben mantener conexiones largas, o que no quieren que un timeout se interprete como «no se ha generado nada». Sin ese parámetro, el comportamiento es exactamente el de antes.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Brisa de la tarde junto al mar",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

La forma de la respuesta y el método de sondeo están en la sección «Modo de recibo de aceptación» de la API de generación en modo simple.

Validación de parámetros

Estos casos devuelven HTTP 400, y el message del error nombra el campo inválido:

• style_weight o weirdness_constraint no es un número.
• Un valor numérico está por debajo de 0.0 o por encima de 1.0.
• vocal_gender no es uno de m, f, male, female.

Límites de los campos de texto

Estos campos también devuelven HTTP 400 si son demasiado largos, y nunca entran en generación ni se precobran. La cuenta es por carácter Unicode (un carácter han cuenta como 1) e incluye los espacios iniciales y finales:

El mensaje de error tiene la forma style_tags must not exceed 1000 characters; received 2772: la primera palabra es el campo que se pasó y el final es el recuento medido, así que ante un 400 puedes recortar usando esos dos números en lugar de probar campo a campo. Las convenciones generales están en «Límites de campos de texto» del Resumen de la nueva API.

Respuesta

El endpoint suele devolver un array con 2 canciones. Una petición asíncrona arranca normalmente en pending; guarda el song_id y lee el estado final y la dirección de audio con la API de consulta de canciones. Los campos de canción son los mismos que en la API de generación en modo simple.

Campos compatibles

Las integraciones nuevas deben usar snake_case en todo. Si una misma petición lleva snake_case y camelCase, prevalece el valor en snake_case.