> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno 声音克隆 API 对接说明

> Suno Music Generation API guide - Ace Data Cloud

SUNO permite crear personajes de voz personalizados a partir de cualquier archivo de audio, logrando la clonación de voz para la generación musical. A diferencia de la API de Persona existente (que utiliza el `audio_id` generado por Suno), esta API acepta una `audio_url` de acceso público, es decir, tu propia grabación de voz. Este documento explica cómo integrar la API de clonación de voz.

## Primer paso: crear un personaje de voz

Esta API tiene tres parámetros de entrada: `audio_url` (obligatorio), que es una URL de un archivo de audio en formato MP3 o WAV accesible públicamente, que contenga una voz clara de una sola persona; `name` y `description` (opcionales), que son el nombre y la descripción del personaje de voz.

> **Requisitos del archivo de audio**
>
> * El formato de audio debe ser `WAV` o `MP3`
> * La duración del audio debe estar entre `10~240 segundos`, se recomienda usar material de voz limpia de una sola persona de `30~60 segundos`
> * El audio debe contener **una voz clara y reconocible de una sola persona hablando o cantando**
> * Evitar **ruido de fondo, acompañamiento, ecos, reverberación**; las canciones completas con acompañamiento generalmente no pueden pasar la verificación de huella de voz
> * No debe incluir **varias personas hablando** o **múltiples voces**
> * Material con volumen demasiado bajo, voz poco clara o ruido excesivo puede resultar en **fallos de clonación** o **resultados de baja calidad**
>   **Restricciones de uso**
> * Los personajes de voz creados mediante la carga de audio son **recursos privados**
> * Este personaje de voz **no es reutilizable entre cuentas**
> * Se recomienda usarlo lo antes posible después de la creación, ya que no usarlo durante mucho tiempo puede resultar en **invalidez o inutilidad**
> * El `name` devuelto es generado automáticamente por el sistema, por favor, usa el `persona_id` devuelto como referencia

> **Si la llamada falla, por favor intenta de nuevo**
> La clonación de voz es una tarea intensiva en recursos, incluso si el material es completamente conforme, existe una probabilidad de fallos ocasionales, como el retorno `voices_sound_different` (verificación de huella de voz no aprobada). **Este tipo de fallos no está relacionado con la calidad del audio, reintentar con el mismo material generalmente tendrá éxito**,
> se sugiere implementar 1 a 2 reintentos automáticos para los resultados fallidos. Las solicitudes fallidas no serán cobradas.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3",
  "name": "My Voice",
  "description": "Ejemplo de voz clara de una sola persona"
}'
```

> La URL `https://cdn.acedata.cloud/suno_demo.mp3` es un material de ejemplo que se puede llamar directamente (MP3, 41 segundos, voz limpia de una sola persona).
> Si necesitas un ejemplo en formato `WAV`, puedes usar
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765` (WAV, 41 segundos, mono 44.1kHz).

El resultado es el siguiente:

```json theme={null}
{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}
```

Como se puede ver, el campo `persona_id` de `data` es el ID del personaje de voz creado. El campo `is_public` siempre es `false`, ya que los personajes de voz creados mediante la carga de audio son privados. Ten en cuenta que el `name` devuelto es generado automáticamente por el sistema, y en adelante, usa el `persona_id` para referenciar a este personaje de voz.

## Segundo paso: usar el personaje de voz para generar música

Una vez que tenemos el ID del personaje de voz, podemos usar la [API de Generación de Audios de Suno](https://platform.acedata.cloud/documents/suno-audios) para generar música. Establece `action` como `generate`, y `persona_id` como el ID del personaje de voz devuelto anteriormente, la canción generada utilizará la voz clonada para cantar.

> **Nota:** La clonación de voz solo es compatible con modelos `chirp-v4-5` y superiores (como `chirp-v4-5`, `chirp-v5`, `chirp-v5-5`), no es compatible con `chirp-v4`.

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "chirp-v5-5",
  "prompt": "Una cálida canción synth-pop sobre noches en la ciudad",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

El resultado es el siguiente:

```json theme={null}
{
  "success": true,
  "task_id": "53d8a334-a972-43c5-895e-60c4454e88d5",
  "data": [
    {
      "id": "16463960-077c-4700-bbb3-3c7897b943d3",
      "title": "Soft Neon on My Skin",
      "audio_url": "https://cdn1.suno.ai/16463960-077c-4700-bbb3-3c7897b943d3.mp3",
      "image_url": "https://cdn2.suno.ai/image_16463960-077c-4700-bbb3-3c7897b943d3.jpeg",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "prompt": "Una cálida canción synth-pop sobre noches en la ciudad",
      "duration": 156.28
    }
  ]
}
```

Como se puede ver, la canción generada utiliza la voz clonada para cantar. El `persona_id` también se puede usar en combinación con la acción `cover` para reinterpretar canciones existentes con la voz clonada.