Skip to main content
GET
Regras gerais do Suno V6 e consulta de tarefas
Todas as APIs Suno de geração, edição e ferramentas usam tarefas assíncronas: envie a operação, obtenha task_id e consulte o resultado com a API desta página.

Autenticação

string
obrigatório
Autenticação Bearer Token: Authorization: Bearer <YOUR_API_KEY>.
Acesse a página de gerenciamento de API Key para obter sua API Key.

Versão V6 e seleção do modelo

Modelos públicos aceitam estas versões:
  • v6
  • v6-wild
  • v6-mini
O endpoint principal exige version ou o custom_model_id retornado por uma tarefa de criação. Operações de edição compatíveis usam v6 quando version é omitida. Não envie version pública com custom_model_id.
custom: true seleciona o modo de letra personalizada; custom_model_id, um modelo treinado. São conceitos diferentes e o modo de letra não muda automaticamente para a tarifa do modelo.

Opções gerais de geração V6

Envie os campos a seguir somente quando aparecerem no endpoint específico: Omita campos não aceitos e não envie max_mode: false em todas as operações. variety e Max são independentes; variety: "max" não ativa a cobrança Max.

Limites de texto e pesos

Novas solicitações de operações usam weirdness; weirdness_constraint é um alias. A geração principal continua usando weirdness_constraint. O tamanho é contado em caracteres Unicode.

Faixa de origem de referência

Com base em obras existentes:
  • task_id: ID de tarefa do API Mart para a faixa de áudio de saída.
  • audio_index: posição original em data.result.music[] da tarefa de origem, a partir de 1; padrão 1.
Exiba a quantidade real do array sem fixá-la em 2. Mesmo que a ordem visual mude, operações posteriores devem usar o índice do resultado original.
Novas solicitações referenciam a faixa de origem com task_id + audio_index; audio_id, music_id ou audio_url não substituem esses campos. Origem ausente ou índice fora do intervalo retorna 400.

Resposta do envio

Leia o ID em data[0].task_id. submitted só indica que a tarefa foi aceita, não que o áudio final já esteja disponível.

Consultar tarefa

GET /v1/music/tasks/{task_id} Adicione ?language=zh para receber traduções disponíveis das mensagens de falha. Isso não muda o idioma da música ou da letra.
string
obrigatório
ID da tarefa retornado pela API de envio.
Espere cerca de 3 segundos e consulte a cada 5–10 segundos até data.status ser completed ou failed. O mesmo ID pode ser usado após recarregar a página. Não reenvie POSTs pagos automaticamente por timeout de rede.

Resposta da consulta

integer
Código de status da resposta.
object
Informações da tarefa.

Processamento do resultado

  • Resultados musicais costumam ficar em data.result.music[], mas downloads, letras, MIDI, Persona e modelos personalizados usam estruturas próprias.
  • duration é a duração real e pode ser decimal; a duração alvo pode não coincidir exatamente com o resultado.
  • O peso 0 é válido e não deve ser ocultado por uma verificação falsy do JavaScript.
  • audio_url não termina necessariamente em .mp3. Reproduza ou baixe usando a URL realmente retornada.
  • Com status="unknown", mantenha o ID da tarefa e permita atualização manual sem criar novas tarefas automaticamente.
AbortController pode parar solicitações do navegador e polling, mas não cancela a tarefa do servidor. Não há endpoint para cancelar uma tarefa Suno enviada.