Visão geral da documentação da Suno API

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

Basta registrar-se com um e-mail para criar uma chave de API. Cada geração custa ¥0,6 e devolve 2 músicas, cobrindo download em MP3/WAV, covers, Extend, separação de stems e clonagem de voz. URL base: https://www.suno-api.io.

Esta página apresenta os modelos disponíveis, todos os endpoints de geração e edição, como funciona a cobrança e a ordem recomendada de leitura. Se é a sua primeira integração, leia de cima para baixo; os roteiros de investigação de 401/403/429 também estão aqui.

Respostas rápidas

Como obtenho uma chave de API? Registe-se com um e-mail, abra o console, vá a gestão de tokens e crie um token. Não é preciso número de telefone nem cartão.

Quanto custa cada chamada? Uma geração custa ¥0,6 e devolve 2 músicas. Consultas de estado, WAV, letras com marcação temporal e sugestões de prompt não têm custo adicional.

Que modelos são suportados? suno-v6 (predefinido), suno-v6-wild e suno-v6-mini. Os modelos de geração normal v5.5 e anteriores foram retirados; os trabalhos existentes não são afetados.

Qual é a URL base? https://www.suno-api.io, com o cabeçalho Authorization: Bearer YOUR_API_KEY.

Modelos disponíveis neste momento

Os modelos que o cliente pode indicar na geração normal de músicas são suno-v6, suno-v6-wild e suno-v6-mini. Se model for omitido, é usado suno-v6.

Os modelos normais suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 e suno-v5-5 foram retirados. Tarefas históricas podem ainda mostrar esses nomes, mas isso é apenas histórico e não significa que o modelo possa ser usado em novos pedidos. A separação de stems é a exceção — ver API de stems (separação de voz/acompanhamento).

Autenticação

Todos os endpoints públicos com chave de API usam os mesmos cabeçalhos:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL base:

https://www.suno-api.io

Convenções gerais dos parâmetros

• Um number no corpo do pedido tem de ser um número JSON, nunca uma percentagem em texto. Uma intensidade de 50% escreve-se 0.5, nunca 50 ou 50%.
• Um boolean tem de ser true ou false. Não envie true, false, 0 ou 1 como substitutos.
• Os campos marcados como "não" podem ser omitidos por completo. Quando não tiver a certeza do que um parâmetro faz, omita-o e deixe o serviço usar o comportamento predefinido; não envie uma string vazia, null ou 0 em vez de "não enviado", porque 0 é um valor válido em alguns campos numéricos.
• Os nomes dos campos são sensíveis à grafia. Cada página de endpoint lista o campo recomendado e os aliases compatíveis; envie exatamente como a tabela mostra. Onde a documentação diz que snake_case e camelCase são ambos aceites, não envie os dois ao mesmo tempo.
• Todos os campos de duração terminados em _s ou Seconds estão em segundos e aceitam decimais. Os timestamps Unix são descritos em separado, incluindo se estão em segundos ou milissegundos.
• Um ID que começa por pending: é um marcador de posição da plataforma, não um ID real de música. Use-o apenas onde o endpoint documenta explicitamente esse suporte; caso contrário, aguarde o song_id real.

Limites de campos de texto

Exceder um limite devolve HTTP 400 diretamente: nada é gerado, nada é pré-cobrado e nenhum registo de tarefa é criado. A contagem é feita por caracteres Unicode (um caractere chinês conta como 1) e os espaços no início e no fim também contam.

A message de erro indica o campo em falta e o comprimento medido, por isso esses dois números bastam para ajustar o texto:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Aplica-se a: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Uma exceção: o campo description de POST /api/music/sounds está limitado a 100 caracteres, porque o caminho dos efeitos sonoros usa o limite mais curto da plataforma.

Geração assíncrona e endereços de áudio

Os endpoints de geração musical funcionam de forma assíncrona por predefinição. Quando a primeira resposta traz status igual a pending, submitted ou processing, um audio_url, video_url ou cover_url vazio é normal e não significa que a tarefa falhou. Guarde o song_id real (ou o client_request_id devolvido) e faça polling no endpoint de consulta correspondente; só leia e descarregue um endereço de áudio quando o estado estiver concluído.

⚠️ Os endereços de áudio expiram em 7 dias — transfira os ficheiros a tempo

audio_url, wav_url, video_url e os endereços devolvidos pelos endpoints de download são servidos pelo armazenamento de objetos da plataforma e expiram por predefinição após 7 dias (os ficheiros são reciclados; um endereço antigo devolve 404 / falha o download).

• Nesses 7 dias, mova os ficheiros para o seu próprio armazenamento (o seu armazenamento de objetos, uma CDN ou um disco de servidor). Não trate os nossos endereços como ligações de longa duração.
• Um endereço expirado não exige regenerar a música e não custa nada extra: volte a chamar a API de consulta de músicas (ou a API de download de media) para obter um endereço novo e válido para essa música.

Tempos de espera e configuração de timeout

Os endpoints de geração são síncronos: o pedido só é aceite e entregue à plataforma quando a resposta chega. Antes disso, o serviço tem de agendar uma conta e passar a verificação de segurança necessária, e não existe resposta intermédia — nenhum outro endpoint consegue ver o pedido. Por isso, a única prova fiável de que "algo foi gerado" é a própria resposta, não aquilo que se observa enquanto se espera.

Tempos de espera medidos (produção, família /api/music/create, 2026-09-18 a 2026-09-20)

• Cerca de 10% dos pedidos demoram mais de 30 segundos e cerca de 1% demora 1–2 minutos. Um pedido lento costuma significar que este teve de passar primeiro por uma verificação de segurança.
• Os campos do pedido, a forma da resposta, os códigos de erro e a cobrança não mudaram, pelo que as integrações existentes só precisam de aumentar o timeout do cliente — nenhuma outra alteração de código.

Requisitos de integração

1. Defina o timeout do cliente para 300 segundos ou mais. Clientes com 30, 60 ou 120 segundos por predefinição desligam-se durante a espera.
2. Não receber resposta não significa que nada foi gerado. Com um timeout ou ligação caída, o pedido pode já ter sido aceite e estar a gerar.
3. Não repita imediatamente após um timeout: uma submissão duplicada cria um segundo pedido e volta a cobrar.
4. Se a ligação caiu, liste as suas músicas com GET /api/music/songs (mais recentes primeiro) um pouco mais tarde — os pedidos aceites aparecem normalmente. Só volte a submeter depois de confirmar que o pedido não existe.
5. Ao reportar um problema, inclua o cabeçalho de resposta X-Oneapi-Request-Id para que o pedido exato possa ser localizado.

Prefere não manter uma ligação longa? Use o modo de recibo de aceitação. POST /api/music/create e POST /api/music/create/custom aceitam um recibo opcional: acrescente "accept_mode": "async" ao corpo (ou o cabeçalho X-Accept-Mode: async) e o endpoint devolve 202 de imediato com um número de recibo, enquanto a geração continua em segundo plano; consulte o progresso em GET /api/music/requests/{request_id}. Um cliente com apenas algumas dezenas de segundos de timeout deixa de poder confundir "sem resposta" com "nada gerado" e deixa de poder cobrar duas vezes por repetições. Ver "Modo de recibo de aceitação" na API de geração em modo simples.

Para referência: python requests usa timeout=300, urllib usa urlopen(..., timeout=300), Node usa req.setTimeout(300000), curl usa --max-time 300.

Lista de endpoints recomendados

Os endpoints /api/voice/clone/* e /api/music/generate-with-voice pertencem à cadeia inicial de clonagem de voz e não são recomendados para novas integrações; use antes a 【Recomendado】 API de perfil de voz.

Parâmetros avançados: Max Mode e Variety

Os endpoints de geração suportam estes dois parâmetros opcionais (omitir mantém o comportamento e o preço anteriores):

Endpoints que os suportam: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• O dobro do preço na prática: um endpoint que custa ¥0,6 por chamada passa a ¥1,2 com max_mode; gerar com uma voz escolhida custa ¥1,2 por chamada e ¥2,4 com Max Mode; o cover de voz da 【Recomendado】 API de perfil de voz também custa ¥1,2 por chamada (¥2,4 com max_mode).
• variety só se aplica à família suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); enviá-lo com qualquer outro modelo devolve 400.
• Efeitos sonoros, stems, concat, WAV e as ações de edição do Studio (crop, remover secção, fade, reverse, speed e afins) não aceitam estes parâmetros — enviá-los explicitamente devolve 400, para que um parâmetro nunca seja ignorado em silêncio.
• variety é o inteiro 0-4; style_weight e weirdness_constraint são decimais de 0 a 1, portanto as escalas são diferentes.

Campos de resposta comuns das músicas

Os endpoints de geração, cover, extend, separação e consulta devolvem normalmente um array de músicas com estes campos:

Quatro passos para integrar (exemplo mínimo)

Com estes quatro passos obtém a sua primeira música; a lista completa de campos de cada passo está na página correspondente da lista de endpoints recomendados.

# 1) Submeter uma geração: ¥0,6, devolve 2 músicas
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Brazilian pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Fazer polling até status ser completed (3-5 segundos é um bom intervalo)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "o song_id devolvido no passo 1"}'

# 3) Obter um endereço de media: os endpoints de leitura são grátis; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "o mesmo song_id", "kind": "song"}'

Quando algo falha: 401 / 402 / 403 / 429 estão no guia de erros; timeouts e cobranças duplicadas na secção "Tempos de espera e configuração de timeout" acima; o detalhe de cada endpoint na lista de endpoints recomendados abaixo.

Recomendações

• Novas integrações devem usar suno-v6 em todos os pedidos.
• Nos endpoints que indicam um preço predefinido, o valor cobrado segue a configuração de preços atual do back office e o modelo pedido.
• Os endpoints de geração devolvem normalmente uma tarefa primeiro; leia o áudio final através de /api/music/query.
• wait_completion=true bloqueia até terminar e serve para testes de baixo volume; em produção prefira o polling.
• Os endpoints de geração podem demorar bastante a responder — defina o timeout do cliente para 300 segundos ou mais e lembre-se de que "sem resposta" não é o mesmo que "nada gerado"; ver acima "Tempos de espera e configuração de timeout".
• As capacidades de upload, cover, substituição e WAV dependem das contas da plataforma e das permissões do clip de origem; quando falham, leia primeiro o message ou o error_message devolvido.

Sobre esta documentação

Esta página foi reorganizada em torno das capacidades que a Create UI expõe na prática, e as novas integrações devem lê-la primeiro. A documentação antiga da API continua disponível na secção "Documentação antiga da API (compatível)" para quem quiser manter o método anterior.