> ## 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 que criemos personagens de voz personalizados a partir de qualquer arquivo de áudio, realizando clonagem de voz para geração musical. Diferente da API Persona existente (que utiliza o `audio_id` gerado pelo Suno), esta API aceita uma `audio_url` publicamente acessível, ou seja, sua própria gravação de voz. Este documento explica como integrar a API de clonagem de voz.

## Primeiro passo: criar um personagem de voz

Esta API possui três parâmetros de entrada: `audio_url` (obrigatório), que é uma URL de um arquivo de áudio em formato MP3 ou WAV acessível publicamente, contendo uma voz humana clara de uma única pessoa; `name` e `description` (opcionais), que são o nome e a descrição do personagem de voz.

> **Requisitos do arquivo de áudio**
>
> * O formato do áudio deve ser `WAV` ou `MP3`
> * A duração do áudio deve estar entre `10~240 segundos`, recomendando-se o uso de material de voz limpa de `30~60 segundos`
> * O áudio deve conter **fala ou canto de uma única pessoa, clara e identificável**
> * Evite **ruído de fundo, acompanhamento, eco, reverberação**; músicas completas com acompanhamento geralmente não passam na verificação de voz
> * Não inclua **múltiplos falantes** ou **várias vozes**
> * Materiais com volume muito baixo, fala pouco clara ou ruído excessivo podem resultar em **falha de clonagem** ou **resultado de baixa qualidade**
>   **Limitações de uso**
> * Os personagens de voz criados por upload de áudio são **recursos privados**
> * Este personagem de voz **não suporta reutilização entre contas**
> * Recomenda-se usar o personagem logo após a criação, o não uso por longos períodos pode resultar em **expiração ou indisponibilidade**
> * O `name` retornado é gerado automaticamente pelo sistema, por favor, use o `persona_id` retornado como referência

> **Se a chamada falhar, tente novamente**
> A clonagem de voz é uma tarefa intensiva em computação, mesmo que o material esteja totalmente em conformidade, há uma certa probabilidade de falhas ocasionais, como o retorno `voices_sound_different` (verificação de voz não aprovada). **Essas falhas não estão relacionadas à qualidade do áudio, e tentar novamente com o mesmo material geralmente resulta em sucesso**,
> recomenda-se implementar 1 a 2 tentativas automáticas em caso de falha. Solicitações falhadas não serão 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": "Minha Voz",
  "description": "Exemplo de voz clara de uma única pessoa"
}'
```

> A `https://cdn.acedata.cloud/suno_demo.mp3` é um material de exemplo que pode ser chamado diretamente (MP3, 41 segundos, voz limpa de uma única pessoa).
> Para um exemplo em formato `WAV`, você pode usar
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765` (WAV, 41 segundos, mono 44.1kHz).

O resultado é o seguinte:

```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
  }
}
```

Pode-se ver que o campo `persona_id` em `data` é o ID do personagem de voz criado. O campo `is_public` é sempre `false`, pois os personagens de voz criados por upload de áudio são privados. Note que o `name` retornado é gerado automaticamente pelo sistema, e posteriormente, utilize o `persona_id` para referenciar esse personagem de voz.

## Segundo passo: usar o personagem de voz para gerar música

Com o ID do personagem de voz, podemos usar a [API de Geração de Áudios do Suno](https://platform.acedata.cloud/documents/suno-audios) para gerar música. Defina `action` como `generate` e `persona_id` como o ID do personagem de voz retornado acima, a música gerada será cantada com a voz clonada.

> **Nota:** A clonagem de voz suporta apenas modelos `chirp-v4-5` e superiores (como `chirp-v4-5`, `chirp-v5`, `chirp-v5-5`), não suportando `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": "Uma canção synth-pop quente sobre noites na cidade",
  "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

O resultado é o seguinte:

```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": "Uma canção synth-pop quente sobre noites na cidade",
      "duration": 156.28
    }
  ]
}
```

Pode-se ver que a música gerada foi cantada com a voz clonada. O `persona_id` também pode ser usado em conjunto com a ação `cover` para regravar músicas existentes com a voz clonada.