API de clonación de voz y generación con voz (no recomendado)

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

⛔ Cadena antigua, no recomendada para nuevas integraciones. Esta página describe la cadena persona inicial (voice_task_id / generate-with-voice). Sigue funcionando, pero ya no se recomienda a los clientes; el menú de la izquierda la marca como "no recomendado".

Para nuevas integraciones usa la 【Recomendado】 API de perfil de voz: crea un perfil de voz a partir de una muestra vocal (POST /api/music/voice-profile/create) y úsalo para versionar una canción concreta o para cantar una canción nueva. El perfil de voz es un recurso de primera clase: se puede listar, consultar y eliminar, y su audio de origen se conserva de forma permanente.

Si tu producto necesita el circuito completo "crear una voz → reutilizarla a largo plazo → versionar canciones", da prioridad a la cadena nueva.

Aviso importante: una voz clonada puede caducar.

El voice_id / voice_task_id que genera la clonación de voz no es un recurso utilizable para siempre: puede dejar de funcionar por su período de validez, por el estado de la cuenta o por cambios en el estado de la voz. Quien integra no debe clonar una vez y reutilizar para siempre un ID de voz guardado en caché local.

Práctica recomendada:

• Guarda voice_task_id, voice_id, is_available, updated_at y la hora de la última generación correcta.
• Antes de cada generación con una voz clonada, llama a GET /api/voice/clone/tasks/{voice_task_id} o a POST /api/voice/clone/tasks/{voice_task_id}/check y confirma que is_available=true.
• Si el endpoint devuelve que la voz no está disponible, que la tarea no existe o selected voice is not ready, pide al usuario que vuelva a clonar o que elija otra voz disponible.
• No prometas al usuario final que una voz clonada es un "activo permanente"; muestra en la interfaz del producto que "la voz puede caducar y requerir una nueva validación o una nueva clonación".

Descripción del endpoint

Este grupo de endpoints crea una voz reutilizable y genera canciones con ella. Quien llama solo necesita la API Key que emite la plataforma; el servidor se encarga de enviar la tarea, sincronizar el estado, facturar y descargar.

Autenticación: Authorization: Bearer YOUR_API_KEY

Facturación:

• Validación de voz, clonación de voz, consulta de estado, eliminación y descargas: gratis.
• La entrada de clonación en un paso del espacio de trabajo: 5 ¥ fijos por llamada; completa automáticamente la validación de la voz de origen y el segundo audio de verificación, y devuelve el importe si falla.
• Seguir generando automáticamente el audio de verificación tras una clonación normal: 5 ¥ fijos por llamada; si falla se devuelve el importe según el flujo actual.
• Generar una canción con una voz clonada: de pago, 1,2 ¥ fijos por llamada; cada llamada suele devolver 2 tareas de marcador de posición.
• Con Max Mode activado (max_mode: true en POST /api/music/generate-with-voice), los 1,2 ¥ por llamada se facturan al doble, es decir 2,4 ¥ por llamada; la generación con voz también admite variety (0-4, sin coste adicional); las reglas de valor están en la sección "Parámetros avanzados" del panorama de la nueva API.

Flujo de llamadas

1. Llama a POST /api/voice/clone/validate para subir la voz de origen y obtener un voice_task_id.
2. Espera o consulta GET /api/voice/clone/tasks/{voice_task_id} hasta obtener validate_info.
3. El usuario lee ese texto en voz alta y graba el audio de verificación.
4. Llama a POST /api/voice/clone/tasks/{voice_task_id}/generate para enviar el audio de verificación.
5. Llama a POST /api/voice/clone/tasks/{voice_task_id}/check o sigue consultando la tarea hasta que is_available=true.
6. Llama a POST /api/music/generate-with-voice para generar una canción con esa voz.
7. El endpoint de generación devuelve primero tareas de marcador de posición; cuando la generación termina y tienes el song_id real, puedes usar los endpoints de descarga para bajar un archivo suelto o un paquete.
8. (Opcional) Cuando ya no necesites la voz, llama a DELETE /api/voice/clone/voices/{voice_task_id} para eliminarla; la semántica está en la sección 6.

También existe la clonación en un paso: en la primera página de grabación/subida de voz del espacio de trabajo puedes elegir terminarlo todo de una vez y el sistema completa la validación y la creación de la voz juntas, así que no tienes que grabar un segundo audio de verificación; cuesta 5 ¥ por llamada y se devuelve el importe si falla.

Campos de la tarea de voz

1. Enviar la voz de origen a validación

Endpoint: POST /api/voice/clone/validate

Parámetros del cuerpo

vocal_end_s - vocal_start_s debe cumplir el mínimo del fragmento de voz. Sube una grabación vocal clara, sin acompañamiento ni ruido evidentes.

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Mi voz femenina en chino",
    "description": "Voz femenina en chino, clara y natural",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mi voz femenina en chino",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Consultar una tarea de voz

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Ejemplo de petición

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mi voz femenina en chino",
      "validate_info": "Lee en voz alta el texto de verificación que se devuelve aquí",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Volver a generar el texto de verificación

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Úsalo cuando el texto de verificación no sea adecuado para leerlo en voz alta o cuando haya que rehacer la validación.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Enviar el audio de verificación y crear la voz

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Parámetros del cuerpo

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Mi voz femenina en chino"
  }'

5. Comprobar si la voz está disponible

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Cuando la tarea está disponible, is_available en la respuesta es true y se devuelve un voice_id.

6. Eliminar una voz

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Facturación: gratis.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Qué ocurre tras la eliminación

• La voz ya no puede generar canciones nuevas: llamar a POST /api/music/generate-with-voice con ese voice_task_id (o con su voice_id) se rechaza con el mensaje selected voice is not ready, sin cargo alguno.
• Las canciones ya generadas con ella no se ven afectadas en absoluto: reproducción, descarga, continuación, sustitución y separación siguen funcionando.
• La tarea de voz desaparece de las consultas: GET /api/voice/clone/tasks/{voice_task_id} devuelve record not found.
• El audio de origen se conserva según la política de retención permanente de la plataforma (desde el 2026-09-23, eliminar ya no borra la muestra vocal que subiste), pero eso no significa que se pueda restaurar: esa tarea antigua ya ha terminado y, para seguir usando la misma voz, hay que recorrer de nuevo el flujo de clonación, que devolverá un voice_task_id nuevo.
• Eliminar dos veces: eliminar la misma tarea otra vez devuelve record not found (ya está en estado eliminado y no se puede consultar).

7. Generar una canción con una voz clonada

Endpoint: POST /api/music/generate-with-voice

Facturación: 1,2 ¥ por llamada.

Parámetros del cuerpo

Se admiten suno-v6, suno-v6-wild y suno-v6-mini; un modelo vacío se trata como suno-v6. Los modelos antiguos V5/V5.5 están retirados, pero las tareas históricas pueden seguir mostrando los nombres antiguos.

La estructura de petición compartida también interpreta campos de compatibilidad de Create UI como task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId y voiceId, pero no son parámetros válidos de cliente para este endpoint: la tarea de voz debe enviarse como voice_task_id, la verificación opcional de voz como voice_id, y la generación musical con voz nunca lee los campos de sound.

Cómo rellenar los parámetros de generación

• Con customMode=false, prompt lleva la descripción de la canción; con customMode=true, prompt lleva la letra completa, y también hay que rellenar style y title. No envíes la letra al campo de descripción del modo inspiración ni trates una descripción de canción como letra en modo avanzado.
• weirdnessConstraint y styleWeight son proporciones decimales de 0.0 a 1.0; no se puede enviar 50 ni 50%. 0.5 es un valor equilibrado; omitirlos significa "sin especificar" y 0 es un valor explícito válido.
• vocalGender solo acepta m, male, f o female. instrumental es solo un campo de compatibilidad en este endpoint: la generación con voz clonada siempre se trata como canción con voz.
• waitAudio no cambia el comportamiento aquí; el endpoint siempre devuelve tareas de marcador de posición de forma asíncrona. Que audio_url esté vacío en el resultado inicial es normal: consulta con client_request_id y lee la dirección de audio solo cuando el resultado haya terminado.

Cabeceras

Comportamiento de Idempotency-Key:

• La primera petición escribe un registro de idempotencia persistente antes de facturar;
• Si la misma clave con la misma petición ya se completó, se reproduce la primera respuesta de aceptación, sin segundo cargo ni segunda tarea;
• La misma clave con un cuerpo distinto se rechaza;
• La misma clave que sigue en proceso devuelve un error estable de "en proceso" y solo expone un client_request_id seguro cuando ya se ha generado;
• Si la primera petición con una clave falla, se queda en fallo; reintentar requiere una clave nueva.

Condiciones de versionado con sourceClipId

El versionado desde una fuente en la API de cliente lo gestiona el servidor: el acceso a la canción de origen se resuelve en servidor y el cliente no envía ningún dato de cuenta. Si la operación es posible lo decide la respuesta real del endpoint.

La fuente debe pertenecer al usuario de API actual, ser una canción del espacio de trabajo terminada y que no sea pending:, y tener audio disponible. Se admiten la generación normal, las fuentes de subida normal y la canción final de la subida reforzada; los registros intermedios de la subida reforzada se rechazan antes de facturar. El servidor solo acepta el ID de canción de origen que envía el cliente y nunca un ID de cuenta; una fuente no disponible o sin terminar devuelve error antes de facturar.

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Escribe una canción pop china sobre la orilla del mar en una noche de verano",
    "style": "Mandopop, warm piano, emotional",
    "title": "Brisa de mar en una noche de verano",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Ejemplo de respuesta

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brisa de mar en una noche de verano",
        "prompt": "Escribe una canción pop china sobre la orilla del mar en una noche de verano"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brisa de mar en una noche de verano",
        "prompt": "Escribe una canción pop china sobre la orilla del mar en una noche de verano"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Sobre las tareas de marcador de posición y el song_id final

generate-with-voice es un endpoint de generación asíncrona. Una respuesta correcta solo significa que la tarea de generación se ha enviado, no que la canción esté terminada.

Significado de los campos clave de la respuesta:

Atención: un placeholder_id que empieza por pending: no sirve como song_id final ni puede pasarse a /api/music/query ni a los endpoints de descarga. Llamar a /api/music/query solo con valores pending:* puede devolver un array vacío [], porque la canción real aún no ha terminado o la tarea de marcador de posición todavía no se ha sustituido por el ID final.

Ejemplo incorrecto:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Flujo correcto:

1. Llama a POST /api/music/generate-with-voice para enviar la tarea de generación con voz.
2. Guarda client_request_id, items[].placeholder_id y items[].client_request_index de la respuesta.
3. Consulta GET /api/music/generate-with-voice/results?client_request_id=cu_xxx en bucle.
4. Cuando items[].song_id tenga valor y no empiece por pending:, llama a /api/music/query, /api/music/download-file o /api/music/download-all.

La versión actual añade un endpoint público de consulta:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Devuelve los resultados de las tareas del mismo client_request_id bajo el usuario actual, para que el cliente pueda consultar por sí mismo el song_id final. En la lista devuelta:

• song_id es el ID real de la canción;
• placeholder_id solo aparece mientras la tarea sigue en estado de marcador de posición;
• un valor que empieza por pending: no puede usarse con /api/music/query ni con los endpoints de descarga.

Si solo guardaste el client_request_id o un ID de marcador de posición pending:*, llama primero a este endpoint de resultados; si aún no aparece el song_id real, envía el client_request_id al soporte técnico para que lo localicen.

Consultar los resultados de la generación con voz

Endpoint: GET /api/music/generate-with-voice/results

Facturación: gratis.

Parámetros de query

Ejemplo de petición

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta en proceso

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Brisa de mar en una noche de verano"
      }
    ]
  }
}

Ejemplo de respuesta terminada

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Brisa de mar en una noche de verano",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Valores del status de nivel superior

8. Descargar un archivo suelto

Endpoint: POST /api/music/download-file

Parámetros del cuerpo

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

La respuesta es un flujo de archivo; el Content-Type y el nombre de archivo siguen lo que devuelva el backend.

9. Descargar los recursos de la canción en un paquete

Endpoint: POST /api/music/download-all

Parámetros del cuerpo

Ejemplo de petición

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

El paquete suele contener el audio, la portada y metadata.json; si algún tipo de recurso aún no se ha generado, no se incluye en el archivo comprimido.

Errores habituales

Los errores de este grupo siempre devuelven HTTP 200: decide el resultado por el campo success del cuerpo (false es fallo, con el motivo en message) y no te guíes solo por el código de estado HTTP. La semántica completa de eliminar una voz (si sigue siendo utilizable, si se puede restaurar) está en la sección 6.