【Recomendado】 API de perfil de voz

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

✅ Recomendada para novas integrações. Segundo as avaliações reais de muitos utilizadores, as músicas geradas por esta cadeia preservam muito bem a voz original: a voz da faixa final fica mais próxima da pessoa da amostra que enviou, por isso é a rota que recomendamos atualmente aos clientes.

Comparação: a API de clonagem de voz e geração com voz anterior continua a funcionar, mas o menu marca-a como "não recomendado" e já não é recomendada para novas integrações.

• Data do documento: 2026-09-26
• Âmbito: criar a sua própria voz → usá-la para versionar uma música escolhida / cantar uma música nova → consultar o progresso → descarregar os resultados
• Todos os endpoints, campos e respostas foram verificados com chamadas reais (o que está marcado como "medido" foi verificado em detalhe)

Nota: este documento só descreve os endpoints que tem de chamar. O tratamento de materiais, o agendamento de tarefas e a validação de conteúdo são feitos automaticamente pelo servidor; o cliente não os implementa.

0. Começar em cinco minutos

Quatro passos bastam para transformar uma amostra vocal em duas músicas finais.

① Criar a voz     POST /api/music/voice-profile/create      → obtém voice_id (status=ready)
② Versionar       POST /api/music/voice-profile/cover       → obtém 2 song_id de imediato
③ Consultar       POST /api/music/query                     → consulta até status=completed
④ Descarregar     GET  /api/music/download?song_id=…&kind=mp3

Exemplo mínimo (curl):

API_KEY="sk-a-sua-chave"
BASE="https://www.suno-api.io"

# ① Criar a voz (envie uma amostra vocal; recomenda-se 10 s ou mais e menos de 10 MB)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=A minha voz" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Versionar uma música com essa voz (song_clip_id = o clip id da música a versionar)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntexto da letra…",
        "style_requirements": "folk lento, guitarra acústica",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Consultar (envie vários ids de uma vez, separados por vírgulas)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Descarregar o mp3 quando terminar (só com status=completed obtém ficheiro)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Convenções comuns

1.1 Domínio e ambiente

Todos os caminhos abaixo são relativos ao Base URL; por exemplo, o endereço completo de POST /api/music/voice-profile/create é https://www.suno-api.io/api/music/voice-profile/create.

1.2 Autenticação

Todos os endpoints usam o mesmo cabeçalho de pedido, cujo valor é a chave API que criou na consola:

Authorization: Bearer sk-xxxxxxxx

• O prefixo Bearer é opcional; o prefixo sk- também (Authorization: sk-xxx funciona igual).
• Chave ausente ou inválida → HTTP 401, com um corpo como {"success":false,"message":"…"} (o texto varia com o idioma do pedido).
• Cada chave só pode ver e só pode operar sobre as músicas e vozes da sua própria conta.

1.3 Formatos do corpo do pedido

• Criar uma voz: recomenda-se multipart/form-data (enviar um ficheiro); application/json (um URL ou base64) também é aceite.
• Os restantes endpoints: application/json.

1.4 Dois invólucros de resposta (o cliente só precisa de conhecer estes dois)

Os endpoints de "gestão de vozes" (create / create-from-clip / list / detail / delete) usam o invólucro de negócio:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

O "versionamento com voz" passa pelo canal de geração e usa o invólucro de geração: o sucesso é code/message/data e a falha um objeto error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Como decidir: veja primeiro o código de estado HTTP, depois success === false e por fim code !== 200 ou a presença de error. Uma falha de negócio não garante um HTTP diferente de 200 (os endpoints de gestão de vozes continuam a devolver HTTP 200 em erro), por isso não pode guiar-se apenas pelo código de estado.

1.5 Idempotência

Criar uma voz (incluindo "criar a partir de áudio existente") é realmente idempotente: na mesma chave, reenviar o mesmo client_request_id cria apenas uma voz e a segunda tentativa devolve diretamente o primeiro resultado (success=true, o mesmo voice_id). O uso previsto é o cliente gerar um id próprio (um UUID, por exemplo) e reutilizar o mesmo valor ao repetir após um tempo de espera esgotado.

O envio de um versionamento não deduplica ao nível do pedido (é uma geração faturável), por isso tenha em atenção duas coisas:

1. O identificador de envio vai no cabeçalho X-Create-Ui-Client-Request-Id: <o seu id de envio>. É escrito no registo de tarefas do servidor para facilitar a investigação posterior; não evita uma cobrança duplicada.
2. Tempo de espera esgotado ≠ falha: o pedido pode já ter sido aceite e estar a gerar. Antes de repetir, consulte GET /api/music/songs?p=1&page_size=20 (os parâmetros de paginação são p / page_size; a grafia compatível ps também serve) para ver se já apareceu uma música nova com generation_type=voice_profile_cover, e só reenvie o mesmo pedido se não tiver aparecido.

Os corpos de create e create-from-clip também aceitam um campo client_request_id (ver §3 e §4).

1.6 Resumo da cobrança

Os preços podem ser lidos a qualquer momento num endpoint público, por isso não os fixe no código (ver §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← preço base do versionamento com voz
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← preço da clonagem reforçada
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

O versionamento usa cobrança prévia + devolução em caso de falha:

• Um pedido rejeitado (parâmetros errados, um 4xx/5xx da plataforma, saldo insuficiente em si) não é cobrado: ao enviar com uma voz inexistente o saldo não mudou nada nos testes (delta = 0);
• Uma tarefa aceite que acaba por falhar (incluindo um erro de serviço da plataforma) passa pela via de devolução do servidor e devolve o valor pré-cobrado.

1.7 Dicionário de estados

O status da voz:

O status da música (o valor devolvido pelos endpoints de consulta):

2. Resumo dos endpoints

3. Criar uma voz

POST /api/music/voice-profile/create

Registe um trecho de áudio vocal como "voz" e obtenha um voice_id. Para a plataforma uma voz é simplesmente "um áudio + o seu clip no catálogo", por isso depois de criada com sucesso esse áudio de origem é mantido de forma permanente (para os versionamentos seguintes).

3.1 Três formas de entrada (escolha uma)

Forma A: envio de ficheiro multipart (recomendada)

Content-Type: multipart/form-data

file=<binário de áudio>      # obrigatório
title=<nome da voz>          # opcional; se vazio usa o nome do ficheiro sem extensão
file_name=<nome original do ficheiro>
source_file_name=<nome original do ficheiro>
source_kind=upload|record    # opcional, marca de origem (envio / gravação); predefinição upload
enhanced=false|true          # opcional, true = clonagem reforçada (ver §3.5)
client_request_id=<chave de idempotência>   # opcional
voice_id=<ID próprio>        # opcional, raramente usado

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=A minha voz" \
  -F "source_kind=upload"

Forma B: JSON + um URL de áudio público

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "A minha voz"
      }'

• O URL tem de ser um link direto HTTPS acessível publicamente; o servidor descarrega-o uma vez e guarda-o no nosso armazenamento de objetos.
• Também pode colocar o endereço no campo audio_url, com o mesmo efeito (se enviar ambos, ganha file_url).
• Quando o endereço já está no armazenamento de objetos desta plataforma (*.myqcloud.com/create-ui/voice-source/...) não é descarregado de novo: é registado diretamente.

Forma C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "A minha voz"
}

• Aceita tanto o prefixo data:audio/xxx;base64, como base64 puro.
• O tamanho é limitado (base64 inflaciona 1,33×), por isso use a forma A para ficheiros grandes.

3.2 Requisitos do áudio

3.3 Resposta

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "A minha voz",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Referência de campos (create / list / detail partilham o mesmo conjunto de campos):

created_at / updated_at são marcas temporais em segundos (10 dígitos), não milissegundos.

3.4 Erros frequentes

3.5 Clonagem reforçada (enhanced=true)

Para casos em que "a própria amostra de voz traz letras com direitos / é preciso um envio reforçado". Cobrada ao preço de envio reforçado (10 ¥ por chamada por predefinição, com devolução automática em caso de falha):

• A resposta é imediatamente status=processing + task_id (ainda sem clip_id) e corre de forma assíncrona;
• Enquanto corre, use GET /api/music/voice-profile/{voice_id} para consultar o progresso, que devolve progress_percent / progress_stage / progress_message;
• Ao terminar, status passa a ready e clip_id, audio_url, image_url ficam preenchidos;
• Em caso de falha, status=failed e error_message diz algo como "o envio reforçado falhou; o valor foi devolvido automaticamente, tente novamente mais tarde";
• Uma clonagem reforçada demora bastante mais do que uma criação normal (minutos), por isso não a espere com um tempo de espera síncrono.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=A minha voz" -F "enhanced=true"

4. Criar uma voz a partir de áudio existente

Se prefere não voltar a enviar: copie diretamente um áudio que já tenha enviado ou já tenha gerado como voz. Grátis e idempotente.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: o clip id de um áudio terminado da sua conta (equivalente ao song_id da música).
• Reenviar o mesmo clip não cria um registo novo: devolve diretamente a voz existente com reused: true (medido).

A resposta são todos os campos de §3.3 mais dois campos só de leitura:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Erros (o message tal como é devolvido; recomenda-se mostrá-lo ou localizá-lo):

5. Lista / detalhe / eliminação de vozes

5.1 Lista

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "A minha voz", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Os campos são exatamente os de §3.3. Por predefinição não são devolvidas as vozes eliminadas.

5.2 Detalhe

GET /api/music/voice-profile/{voice_id}

Devolve um único objeto de voz (data é o próprio objeto, não um array). Enquanto uma clonagem reforçada está em curso, acrescenta ainda:

5.3 Eliminar

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Depois de eliminada, a voz desaparece da lista e já não pode ser usada em versionamentos novos: enviar com esse voice_id devolve 400 (ver §6.4).
• 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.
• Eliminar uma voz inexistente, ou que não pertence a esta conta, devolve {"success":false,"message":"voice not found"}.

6. Versionar com uma voz (o endpoint central)

POST /api/music/voice-profile/cover
Content-Type: application/json

Um envio gera 2 músicas (igual à geração normal).

6.1 Dois cenários

O resolved_scene da resposta devolve cover ou sing, para poder confirmar que rota foi seguida.

6.2 Campos do pedido

Recomenda-se enviar também o cabeçalho X-Create-Ui-Client-Request-Id: <o mesmo id de envio>: só isso é escrito no registo de tarefas do servidor e serve de chave principal para a investigação posterior (ver §1.5).

Unidades a vigiar: audio_weight / style_weight / weirdness_constraint são decimais de 0 a 1, variety é um inteiro de 0 a 4 e duration vai em segundos. Misturá-los provoca rejeições ou resultados estranhos.

A letra é opcional no cenário B (o modelo desenrasca-se sozinho), mas envie sempre lyrics quando precisar de cantar um conteúdo específico.

6.3 Resposta

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Tarefa] Isto é um versionamento. … (a parte estrutural fixa do servidor + os requisitos de versionamento/estilo que preencheu)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Pontos-chave:

1. Identifique as músicas finais com clips[].song_id (este endpoint não devolve um campo id).
2. Obtém 2 valores de song_id de imediato, enquanto status ainda está em processing (significa apenas que foram aceites) e audio_url está vazio; tem de consultar até completed antes de descarregar. play_url é o fluxo de pré-escuta da plataforma, pode já aparecer no envio e vai expirar.
3. description é o prompt que o servidor acaba por enviar (a parte estrutural fixa + os cover_requirements / style_requirements que preencheu); é muito útil para investigar resultados.
4. source_updates é o resultado do tratamento de materiais do servidor e o cliente pode ignorá-lo.
5. O title que envia é escrito no registo de tarefas do servidor e aparece como song_title nas consultas seguintes; que clips[].song_title venha vazio na resposta do envio é normal.

6.4 Erros

{ "error": { "message": "esta voz não existe ou foi eliminada (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Saldo insuficiente devolve um erro de cobrança logo no envio e nunca deixa uma tarefa a meio.

6.5 Modelos disponíveis (nomes de cara ao cliente)

Use os nomes de modelo de cara ao cliente (os de cima). chirp-* são nomes internos da plataforma e não devem ser usados diretamente.

7. Consultar o progresso

7.1 Consulta em lote (recomendada)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids é uma cadeia separada por vírgulas (não um array).
• A resposta é um array nu (diretamente [...], sem invólucro success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Dois tigres",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Tarefa] Isto é um versionamento. … (o prompt final do servidor)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Conselho de consulta: a cada 5–10 segundos, com um tempo de espera total de 10–15 minutos (a conta fria mais lenta medida demorou cerca de 4,5 minutos; muito poucas demoram mais). Não julgue a conclusão por o audio_url estar vazio: use o status.

Nota de compatibilidade: este endpoint identifica as músicas por song_id; em algumas respostas antigas apareceu um campo id, por isso row.song_id || row.id é a forma segura de o ler.

7.2 Detalhe de uma música

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Dois tigres",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Dois tigres",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Aqui created_at / completed_at são segundos Unix (ao contrário das cadeias ISO da consulta em lote, por isso os clientes devem distingui-los).
• wav_url / video_url são as entradas de descarga desta plataforma (relativas ao domínio atual) e um GET obtém o ficheiro; são cadeias vazias quando a plataforma não produziu esse material.
• parameter_retention indica a que parâmetros de envio essa música pode ser rastreada: core_parameters_available=true significa que os parâmetros centrais (letra / estilo / origem) são consultáveis, e com extended_parameters_available=false os parâmetros estendidos listados acima não foram retidos (os versionamentos com voz estão atualmente nesta categoria).

7.3 A minha lista de trabalhos

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=palavra-chave

Parâmetros de paginação: p (número da página, desde 1) / page_size (itens por página; ps é uma grafia compatível). Opcionais status e q (uma palavra-chave do título). Por predefinição ordena por data de criação descendente.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Dois tigres",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Use generation_type=voice_profile_cover para distinguir "as músicas produzidas por um versionamento com voz" de outros resultados de geração.

8. Descarregar as músicas finais

8.1 Obter o mp3 diretamente (recomendado, grátis)

Qualquer uma das três serve; escolha uma:

1. Usar o audio_url do resultado da consulta (um link direto ao armazenamento de objetos, o mais cómodo).
2. GET /api/music/download?song_id=<id>&kind=mp3 → devolve diretamente o fluxo de bytes de áudio (com o nome do ficheiro já em Content-Disposition).
3. POST /api/music/download-url (para obter um endereço temporário assinado).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Valores de kind: mp3 (equivalente a song) / playback (reprodução em streaming) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) só está disponível para algumas músicas por agora; se falhar, gere o ficheiro você mesmo com a API de letras com marcas temporais. A resposta é o fluxo de bytes do ficheiro, com Content-Type e Content-Disposition (nome do ficheiro) já definidos; os wav_url / video_url que GET /api/music/songs/{song_id} devolve são a mesma entrada com kind=wav|video.

8.2 Converter para wav / obter letras / metadados (pago)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files aceita: mp3 / wav / lyrics / metadata, até 10 músicas de cada vez.
• Cobrado por música bem-sucedida (0,2 ¥ cada); uma música que falha por completo não é cobrada, e um formato que falha aparece apenas em songs[].errors.
• Para voltar a obter ficheiros já obtidos antes, use primeiro o gratuito POST /api/music/free2/cached (os mesmos song_ids + files) para conseguir endereços arquivados; o seu songs[].missing_files lista os formatos que não estão em cache e têm de ser preparados de novo.

9. Consultar preços

GET /api/pricing/catalog

Um endpoint público que não requer autenticação. Todos os preços unitários que o cliente precisa de mostrar estão em data.catalog.meta (cadeias):

Os preços são ajustados no back-office, por isso leia-os ao vivo em vez de os fixar no cliente. A cobrança real do versionamento = voice_generation_price × (max_mode_factor outra vez se max_mode for verdadeiro).

10. Limites e avisos

1. Tamanho do envio: ≤ 10 MB (o servidor aceita mais, mas a gateway de entrada trunca corpos sobredimensionados em 10 MiB, o que se manifesta como "rejeitado pela Suno", por isso bloqueie antes do seu lado).
2. Duração da amostra: pelo menos 6 s, recomenda-se 10–60 s; se for demasiado curta a plataforma rejeita.
3. Conteúdo da amostra: voz limpa; evite qualquer coisa muito parecida com uma gravação existente (a comparação do catálogo rejeita-a).
4. Limites de texto: lyrics ≤ 3000 caracteres; aconselha-se que style_requirements / negative_tags / title fiquem em 1000 / 1000 / 100 caracteres respetivamente (os requisitos de estilo e de versionamento são concatenados ao prompt, por isso mantenha o total dentro de 3000 caracteres).
5. A letra não é reescrita: canta-se o que passar (carácter a carácter), sem truncagem local.
6. Cada música produz 2 faixas; não assuma um único resultado.
7. O áudio de origem é mantido de forma permanente: eliminar uma voz não limpa o seu áudio de origem; assim mantêm-se possíveis os versionamentos seguintes e a rastreabilidade de conformidade.
8. A voz tem de estar pronta: uma voz em processing não pode ser usada em versionamentos.
9. Tempo de espera do pedido: numa conta fria o primeiro envio demorou até cerca de 4,5 minutos nos testes, por isso configure o tempo de espera do cliente em ≥ 6 minutos. Os versionamentos não deduplicam ao nível do pedido, por isso após um tempo de espera esgotado verifique se já apareceu uma música nova (§1.5) antes de decidir reenviar.
10. Titularidade da voz: as vozes pertencem a quem as cria; um versionamento só aceita vozes prontas e não eliminadas. Uma voz que não existe, foi eliminada ou pertence a outra conta devolve 400: esta voz não existe ou foi eliminada (voice_id=…).

11. Perguntas frequentes (FAQ)

Q1. Criar uma voz custa dinheiro? A criação normal e "criar a partir de áudio existente" são grátis; só são cobrados os versionamentos (1,2 ¥ / MAX 2,4 ¥) e as clonagens reforçadas (10 ¥ por predefinição).

Q2. Posso usar como amostra uma música final com acompanhamento? Não se recomenda. Qualquer coisa com música, ou muito parecida com uma gravação existente do catálogo, é rejeitada pela plataforma (This audio matches an existing recording in our catalog.). Use uma gravação puramente vocal e seca.

Q3. Porque é que o audio_url está vazio depois de enviar um versionamento? O envio apenas significa que foi aceite e o status continua em processing. Um endereço reproduzível/descarregável aparece quando consultar /api/music/query até status=completed.

Q4. É preciso enviar letra no cenário B (sem song_clip_id)? É opcional. Envie lyrics para cantar um conteúdo específico; sem ele o modelo desenrasca-se sozinho, mas com menos controlo.

Q5. Um áudio enviado pelo cliente pode ser usado diretamente como voz? Sim: através da forma file_url do create, ou enviando-o primeiro como música e chamando depois create-from-clip.

Q6. O dinheiro é devolvido se falhar? Um pedido rejeitado de imediato (parâmetros errados / erro da plataforma) não é cobrado, segundo as medições; uma tarefa aceite que acaba por falhar devolve o valor pré-cobrado. Na falha terminal a tarefa informa status=failed mais error_message.

Q7. Depois de eliminar uma voz, ainda posso ouvir músicas geradas antes com ela? Sim. A eliminação só afeta se essa voz pode ser usada em versionamentos novos.

Q8. Que duração de música posso versionar de uma vez? duration aceita de 1 a 480 segundos; se o omitir decide a plataforma a partir da música original / do material. Atenção: as faixas finais da plataforma têm no mínimo cerca de 30 segundos; com um valor menor os testes continuavam a dar 29,96 / 29,76 segundos.

Anexo A: exemplo completo (Node.js, com consulta e descarga)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Criar a voz (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Versionar
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "folk lento, guitarra acústica",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Consultar até concluir (a cada 5 segundos, no máximo 15 minutos)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // array nu
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Descarregar
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "A minha voz");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nletra…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Anexo B: registo de alterações