API de clonagem de voz e geração com voz (não recomendado)

Atualizado em 2026-09-18 · equipe Suno-API

⛔ Cadeia antiga, não recomendada para novas integrações. Esta página descreve a cadeia persona inicial (voice_task_id / generate-with-voice). Continua a funcionar, mas já não é recomendada ao cliente; o menu da esquerda marca-a como "não recomendado".

Para novas integrações use a 【Recomendado】 API de perfil de voz: crie um perfil de voz a partir de uma amostra vocal (POST /api/music/voice-profile/create) e use-o para fazer uma versão de uma música escolhida ou para cantar uma música nova. O perfil de voz é um recurso de primeira classe: pode ser listado, consultado e eliminado, e o áudio de origem é mantido de forma permanente.

Se o seu produto precisa do circuito completo "criar uma voz → reutilizar a longo prazo → versionar músicas", dê prioridade à cadeia nova.

Aviso importante: uma voz clonada pode expirar.

O voice_id / voice_task_id gerado pela clonagem de voz não é um recurso utilizável para sempre: pode deixar de funcionar pelo período de validade, pelo estado da conta ou por alterações no estado da voz. Quem integra não deve clonar uma vez e reutilizar para sempre um ID de voz guardado em cache local.

Prática recomendada:

• Guarde voice_task_id, voice_id, is_available, updated_at e a hora da última geração bem-sucedida.
• Antes de cada geração com uma voz clonada, chame GET /api/voice/clone/tasks/{voice_task_id} ou POST /api/voice/clone/tasks/{voice_task_id}/check e confirme que is_available=true.
• Se o endpoint devolver voz indisponível, tarefa inexistente ou selected voice is not ready, peça ao utilizador para clonar de novo ou escolher outra voz disponível.
• Não prometa ao utilizador final que uma voz clonada é um "ativo permanente"; mostre na interface do produto que "a voz pode expirar e precisar de nova validação ou nova clonagem".

Descrição do endpoint

Este grupo de endpoints cria uma voz reutilizável e gera músicas com ela. Quem chama só precisa da API Key emitida pela plataforma; o servidor trata do envio da tarefa, da sincronização de estado, da cobrança e das descargas.

Autenticação: Authorization: Bearer YOUR_API_KEY

Cobrança:

• Validação de voz, clonagem de voz, consulta de estado, eliminação e descargas: grátis.
• A entrada de clonagem num passo do espaço de trabalho: 5 ¥ fixos por chamada; conclui automaticamente a validação da voz de origem e o segundo áudio de verificação, e devolve o valor em caso de falha.
• Continuar automaticamente para o áudio de verificação após uma clonagem normal: 5 ¥ fixos por chamada; em caso de falha devolve o valor segundo o fluxo atual.
• Gerar uma música com uma voz clonada: pago, 1,2 ¥ fixos por chamada; cada chamada devolve normalmente 2 tarefas de marcador de posição.
• Com o Max Mode ligado (max_mode: true em POST /api/music/generate-with-voice), os 1,2 ¥ por chamada são cobrados a 2×, ou seja 2,4 ¥ por chamada; a geração com voz também aceita variety (0-4, sem custo adicional); as regras de valor estão na secção "Parâmetros avançados" da visão geral da nova API.

Fluxo de chamadas

1. Chame POST /api/voice/clone/validate para enviar a voz de origem e obter um voice_task_id.
2. Aguarde ou consulte GET /api/voice/clone/tasks/{voice_task_id} até obter validate_info.
3. O utilizador lê esse texto em voz alta e grava o áudio de verificação.
4. Chame POST /api/voice/clone/tasks/{voice_task_id}/generate para enviar o áudio de verificação.
5. Chame POST /api/voice/clone/tasks/{voice_task_id}/check ou continue a consultar a tarefa até is_available=true.
6. Chame POST /api/music/generate-with-voice para gerar uma música com essa voz.
7. O endpoint de geração devolve primeiro tarefas de marcador de posição; quando a geração terminar e tiver o song_id real, pode usar os endpoints de descarga para obter um ficheiro isolado ou um pacote.
8. (Opcional) Quando já não precisar da voz, chame DELETE /api/voice/clone/voices/{voice_task_id} para a eliminar; a semântica está na secção 6.

Também existe a clonagem num passo: na primeira página de gravação/envio de voz do espaço de trabalho pode escolher concluir tudo de uma vez e o sistema faz a validação e a criação da voz juntas, sem precisar de gravar um segundo áudio de verificação; custa 5 ¥ por chamada e devolve o valor em caso de falha.

Campos da tarefa de voz

1. Enviar a voz de origem para validação

Endpoint: POST /api/voice/clone/validate

Parâmetros do corpo

vocal_end_s - vocal_start_s tem de cumprir o mínimo do trecho de voz. Envie uma gravação vocal clara, sem acompanhamento nem ruído evidentes.

Exemplo de requisição

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": "A minha voz feminina em chinês",
    "description": "Voz feminina em chinês, clara e natural",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Exemplo de resposta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "A minha voz feminina em chinês",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Consultar uma tarefa de voz

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

Exemplo de requisição

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

Exemplo de resposta

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "A minha voz feminina em chinês",
      "validate_info": "Leia em voz alta o texto de verificação devolvido aqui",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Gerar de novo o texto de verificação

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

Use quando o texto de verificação não for adequado para leitura em voz alta ou quando for preciso refazer a validação.

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 o áudio de verificação e criar a voz

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

Parâmetros do corpo

Exemplo de requisição

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": "A minha voz feminina em chinês"
  }'

5. Verificar se a voz está disponível

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 '{}'

Quando a tarefa está disponível, o is_available da resposta é true e é devolvido um voice_id.

6. Eliminar uma voz

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

Cobrança: grátis.

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

Exemplo de resposta

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

O que acontece depois da eliminação

• A voz já não pode gerar músicas novas: chamar POST /api/music/generate-with-voice com esse voice_task_id (ou com o seu voice_id) é rejeitado com a mensagem selected voice is not ready, sem qualquer cobrança.
• As músicas já geradas com ela não são afetadas de forma alguma: reprodução, descarga, continuação, substituição e separação continuam a funcionar.
• A tarefa de voz desaparece das consultas: GET /api/voice/clone/tasks/{voice_task_id} devolve record not found.
• O áudio de origem é mantido segundo a política de retenção permanente da plataforma (desde 2026-09-23, eliminar já não apaga a amostra vocal que enviou), mas isso não significa que possa ser restaurado: essa tarefa antiga já terminou e, para continuar a usar a mesma voz, é preciso percorrer de novo o fluxo de clonagem, que devolve um voice_task_id novo.
• Eliminar duas vezes: eliminar a mesma tarefa outra vez devolve record not found (já está no estado eliminado e não pode ser consultada).

7. Gerar uma música com uma voz clonada

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

Cobrança: 1,2 ¥ por chamada.

Parâmetros do corpo

suno-v6, suno-v6-wild e suno-v6-mini são suportados; um modelo vazio é tratado como suno-v6. Os modelos antigos V5/V5.5 foram retirados, mas tarefas históricas podem continuar a mostrar os nomes antigos.

A estrutura de requisição partilhada também interpreta campos de compatibilidade do Create UI como task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId e voiceId, mas não são parâmetros de cliente válidos para este endpoint: a tarefa de voz tem de ser enviada como voice_task_id, a verificação opcional de voz como voice_id, e a geração musical com voz nunca lê os campos de sound.

Como preencher os parâmetros de geração

• Com customMode=false, prompt leva a descrição da música; com customMode=true, prompt leva a letra completa, e também tem de preencher style e title. Não envie a letra para o campo de descrição do modo inspiração nem trate uma descrição de música como letra do modo avançado.
• weirdnessConstraint e styleWeight são proporções decimais de 0.0 a 1.0; não pode enviar 50 nem 50%. 0.5 é um valor equilibrado; omitir significa "sem especificar" e 0 é um valor explícito válido.
• vocalGender só aceita m, male, f ou female. instrumental é apenas um campo de compatibilidade neste endpoint: a geração com voz clonada é sempre tratada como música com voz.
• waitAudio não altera o comportamento aqui; o endpoint devolve sempre tarefas de marcador de posição de forma assíncrona. Um audio_url vazio no resultado inicial é normal: consulte com o client_request_id e leia o endereço do áudio só depois de o resultado terminar.

Cabeçalhos

Comportamento do Idempotency-Key:

• O primeiro pedido escreve um registo de idempotência persistente antes da cobrança;
• Se a mesma chave com o mesmo pedido já estiver concluída, a primeira resposta de aceitação é reproduzida, sem segunda cobrança nem segunda tarefa;
• A mesma chave com um corpo diferente é rejeitada;
• A mesma chave ainda em processamento devolve um erro estável de processamento e só expõe um client_request_id seguro quando já foi gerado;
• Se o primeiro pedido com uma chave falhar, fica em falha; repetir exige uma chave nova.

Condições de versionamento com sourceClipId

O versionamento a partir de uma fonte na API de cliente é tratado no servidor: o acesso à música de origem é resolvido no servidor e o cliente não envia dados de conta. Se a operação é possível decide-o a resposta real do endpoint.

A fonte tem de pertencer ao utilizador de API atual, ser uma música do espaço de trabalho concluída e que não seja pending:, e ter áudio disponível. São suportadas a geração normal, as fontes de envio normal e a música final do envio reforçado; os registos intermédios do envio reforçado são rejeitados antes da cobrança. O servidor só aceita o ID da música de origem enviado pelo cliente e nunca um ID de conta; uma fonte indisponível ou inacabada devolve erro antes da cobrança.

Exemplo de requisição

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": "Escreve uma canção pop chinesa sobre a beira-mar numa noite de verão",
    "style": "Mandopop, warm piano, emotional",
    "title": "Brisa do mar numa noite de verão",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Exemplo de resposta

{
  "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 do mar numa noite de verão",
        "prompt": "Escreve uma canção pop chinesa sobre a beira-mar numa noite de verão"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brisa do mar numa noite de verão",
        "prompt": "Escreve uma canção pop chinesa sobre a beira-mar numa noite de verão"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Sobre as tarefas de marcador de posição e o song_id final

generate-with-voice é um endpoint de geração assíncrona. Uma resposta bem-sucedida significa apenas que a tarefa de geração foi enviada, não que a música esteja concluída.

Significado dos campos principais da resposta:

Atenção: um placeholder_id que começa por pending: não serve como song_id final nem pode ser passado a /api/music/query ou aos endpoints de descarga. Chamar /api/music/query só com valores pending:* pode devolver um array vazio [], porque a música real ainda não terminou ou a tarefa de marcador de posição ainda não foi substituída pelo ID final.

Exemplo incorreto:

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

Fluxo correto:

1. Chame POST /api/music/generate-with-voice para enviar a tarefa de geração com voz.
2. Guarde client_request_id, items[].placeholder_id e items[].client_request_index da resposta.
3. Consulte GET /api/music/generate-with-voice/results?client_request_id=cu_xxx em ciclo.
4. Quando items[].song_id tiver valor e não começar por pending:, chame /api/music/query, /api/music/download-file ou /api/music/download-all.

A versão atual acrescenta um endpoint público de consulta:

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

Devolve os resultados das tarefas do mesmo client_request_id sob o utilizador atual, para o cliente poder consultar por si o song_id final. Na lista devolvida:

• song_id é o ID real da música;
• placeholder_id só aparece enquanto a tarefa está em estado de marcador de posição;
• um valor que começa por pending: não pode ser usado com /api/music/query nem com os endpoints de descarga.

Se só guardou o client_request_id ou um ID de marcador de posição pending:*, chame primeiro este endpoint de resultados; se ainda não encontrar o song_id real, envie o client_request_id ao apoio técnico para o localizarem.

Consultar os resultados da geração com voz

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

Cobrança: grátis.

Parâmetros de query

Exemplo de requisição

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"

Exemplo de resposta em processamento

{
  "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 do mar numa noite de verão"
      }
    ]
  }
}

Exemplo de resposta concluída

{
  "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 do mar numa noite de verão",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Valores do status de nível superior

8. Descarregar um ficheiro isolado

Endpoint: POST /api/music/download-file

Parâmetros do corpo

Exemplo de requisição

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

A resposta é um fluxo de ficheiro; o Content-Type e o nome do ficheiro seguem o que o backend devolver.

9. Descarregar os recursos da música num pacote

Endpoint: POST /api/music/download-all

Parâmetros do corpo

Exemplo de requisição

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

O pacote costuma conter o áudio, a capa e metadata.json; se algum tipo de recurso ainda não tiver sido gerado, não entra no ficheiro comprimido.

Erros frequentes

Os erros deste grupo devolvem sempre HTTP 200: decida o resultado pelo campo success do corpo (false é falha, com o motivo em message) e não olhe apenas para o código de estado HTTP. A semântica completa de eliminar uma voz (se continua utilizável, se pode ser restaurada) está na secção 6.