API de generación de voz hablada (Speech)

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

Descripción del endpoint

Speech convierte un guion de discurso o una descripción de una línea en audio de "habla/discurso", con música de fondo opcional. Encaja en discursos, brindis, narración, guiones de locución, contenido de audio y escenarios similares.

Atención: este endpoint genera audio hablado, no una canción cantada (sin melodía y sin voces cantadas). Si necesitas canto, usa la API de generación en modo simple o la API de generación en modo personalizado.

Endpoint: POST /api/music/speech

Facturación: De pago, actualmente 0,6 ¥ por llamada por defecto. Cada llamada suele devolver 2 audios; el importe realmente cobrado sigue la configuración de precios 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 segundos (1-10 s); pero, como en los demás endpoints de generación síncronos, en casos extremos puede tardar más. 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.

Cumplimiento de contenido: la plataforma revisa el guion por derechos de autor y políticas de contenido. Si se considera que incluye material protegido (por ejemplo citar la letra de otra persona o el texto literal de una obra conocida), esta llamada falla y el importe se devuelve por completo de forma automática. Cambia a tu propia redacción, o convierte la cita en una paráfrasis, y vuelve a intentarlo.

Parámetros de la petición

Headers

Parámetros del body

Este endpoint no admite duration: si lo envías devuelve HTTP 400, no lo ignora en silencio. La duración del discurso la determina la longitud del contenido de script.

Ejemplos de petición

Petición mínima (solo el guion)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "¡Buenos días a todos! Hoy mi charla trata sobre aprovechar bien nuestro tiempo y seguir adelante."
  }'

Petición completa (con tono, género y música de fondo desactivada)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Ejemplo en Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Buenas tardes, compañeros. Les informo del avance de esta semana.',
        'tone': 'sereno y claro, informe de reunión',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # normalmente 2 elementos
for item in items:
    print(item['song_id'], item['status'])

Notas sobre los parámetros

script (el discurso, obligatorio)

• Pega el contenido que quieres decir; también puedes escribir una sola descripción y dejar que el modelo redacte el discurso (por ejemplo "una arenga de medio tiempo para un equipo que va veinte puntos abajo, de un murmullo bajo a un rugido a pleno pulmón").
• Los saltos de línea, los párrafos y las indicaciones escénicas como [pausa] se pueden escribir directamente y el modelo las seguirá en la medida de lo posible.
• El límite es de 3000 caracteres (contados como caracteres Unicode; un carácter chino cuenta como 1); si te pasas, devuelve 400 y no se cobra.

tone (tono y escenario, opcional)

Describe cómo hablar, no qué decir. Conviene incluir cuatro tipos de información: tono, velocidad/ritmo, emoción y escenario.

Enérgico y potente, acelerando desde un ritmo lento, pausas claras; salón de actos, ante todo el alumnado
Cálido y suave, ritmo pausado; banquete de boda
Sereno y contenido, ritmo constante y claro; informe al consejo

El límite es de 1000 caracteres. Si no lo envías, el modelo lo deduce del contenido de script.

gender / vocal_gender (género del hablante, opcional)

• Para voz masculina envía m o male, para femenina f o female; el servidor los normaliza a m / f.
• Los dos nombres de campo funcionan; usa solo uno: gender es la forma recomendada en este endpoint; si ya usas el modo personalizado, puedes seguir usando vocal_gender.
• Omitirlo significa "cualquiera" y decide el modelo.

backing_music (música de fondo, opcional)

• Por defecto true (con música de fondo), igual que en la versión web de Suno.
• false da un discurso solo con voz, útil si luego quieres añadir tu propia música o locución.
• Debe ser un booleano JSON true / false; las cadenas "true" y "1" también se aceptan, pero se recomiendan los booleanos.

model (modelo, opcional)

Los tres modelos de cara al cliente están disponibles al mismo precio (0,6 ¥ por llamada). El discurso lo genera la familia Suno v6; si se omite se trata como suno-v6. Salvo que tengas una preferencia concreta, normalmente no hace falta enviar este campo.

Validación de parámetros y límites de texto

Los siguientes casos devuelven HTTP 400 y todos se bloquean antes del cobro, así que no generan ningún cargo:

Límites de los campos de texto

Pasarse de longitud también devuelve HTTP 400 y no inicia la generación ni pre-cobra nada. El recuento es por caracteres Unicode (un carácter chino cuenta como 1) e incluye los espacios iniciales y finales:

El error tiene la forma script must not exceed 3000 characters; received 4120: la primera palabra es el campo que se pasó y el final es el recuento real, así que ante un 400 puedes recortar directamente con esos dos números.

Respuesta

La respuesta es un array de canciones exactamente igual que el de los demás endpoints de generación (normalmente 2 elementos); guarda el song_id y usa la API de consulta e historial de canciones para ver el estado final y la dirección del audio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Aprovechar bien el tiempo",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Fallo de generación y reembolsos

Cuando la generación falla, el cargo de esa llamada se devuelve por completo de forma automática; no hace falta contactar con soporte. El motivo se ve en la respuesta o en el error_message de la API de consulta e historial de canciones.

El fallo más habitual es que la plataforma considere que el contenido incluye material protegido, por ejemplo:

Your lyrics contain copyrighted material. Please change it and try again.

En ese caso, cambia el guion por tu propia redacción (o convierte la cita en una paráfrasis) y envíalo de nuevo.

Preguntas frecuentes

P: ¿Por qué el resultado es "habla" y no canto? R: Este es el endpoint de discursos y su salida es audio hablado. Para cantar usa los endpoints de generación o de modo personalizado.

P: ¿Por qué devuelve 2 elementos cada vez? R: Como en el resto de endpoints de generación de la plataforma, una generación produce 2 candidatos; consúltalos por separado con song_id y quédate con el que te guste.

P: ¿Cómo controlo la duración? R: La determina la longitud de script; este endpoint no acepta el parámetro duration.

P: ¿Puedo indicar una voz (por ejemplo mi voz clonada)? R: La versión actual no lo admite. El discurso usa un conjunto fijo de voces y gender elige masculina o femenina; si necesitas tu propia voz, usa la capacidad correspondiente de la API de creación de perfil de voz (recomendado).

P: ¿Qué pasa si no envío tone? R: El modelo deduce el tono y el ritmo del contenido de script. Para reproducir un estilo de forma estable, escribe tono, velocidad y escenario en tone.

Campos compatibles

En integraciones nuevas usa snake_case de forma consistente. Los demás campos (script, tone, song_title, backing_music) no tienen alias en camelCase.

Siguientes pasos

Cuando tengas el song_id:

1. Usa la API de consulta e historial de canciones para ver el estado de generación y la dirección del audio;
2. Al terminar, usa la API de descarga y previsualización de medios de canciones para descargarlo o escucharlo;
3. Para descargas por lotes o copiarlo a tu propio almacenamiento, consulta los endpoints del centro de descargas.