Skip to main content
POST
O antigo endpoint POST /v1/music/generations/wav foi descontinuado. Ele permanece temporariamente compatível e equivale ao novo endpoint com formats: ["wav"]. Novas integrações devem usar POST /v1/music/generations/download.
Selecione a música de origem: envie o task_id da tarefa que criou o áudio e use audio_index para escolher uma faixa do resultado music[]. O índice começa em 1 e o padrão é 1.

Autenticação

string
obrigatório
Todas as APIs exigem Bearer Token. Obtenha sua chave na página de chaves de API.

Parâmetros da solicitação

string
padrão:"suno"
Nome do modelo. Use suno; o padrão também é suno.
string
obrigatório
ID da tarefa que criou a música de origem.A tarefa deve pertencer à conta atual, estar concluída e conter áudio para download. Geração, extensão, cover e stems são aceitos; tarefas apenas de texto, como letras ou análise de BPM, não são.
integer
padrão:"1"
Número da faixa no resultado music[].
  • Começa em 1
  • Padrão: 1
  • Não pode exceder o número de faixas da tarefa
string[]
Array de formatos solicitados com pelo menos um item.Valores: mp3, m4a, wav.Vários formatos podem ser solicitados juntos. Maiúsculas e minúsculas são ignoradas, duplicados são removidos e a ordem do resultado segue a solicitação.
string
Para um único formato, pode substituir formats.Exemplo: "format": "mp3"
Use formats ou format. Se ambos faltarem ou o array estiver vazio, a API retorna HTTP 400.

Resposta do envio

O envio bem-sucedido retorna um novo task_id da tarefa de download.
data é um array; leia data[0].task_id. Esse ID pertence à nova tarefa de download e difere do task_id da música enviado na solicitação.

Consultar o resultado

Use o ID da tarefa de download:
Os arquivos normalmente já estão prontos no envio. Consulte uma vez imediatamente; se o status não for completed nem failed, consulte a cada 2 segundos por no máximo 60 segundos.

Concluído

Leia result.files[]:
result.wavUrl existe apenas para compatibilidade com a antiga API WAV. O novo código deve sempre usar result.files[].

Em processamento

Ainda não há result. Continue consultando.

Falha

Tarefas com falha recebem reembolso automático e retornam cost: 0. Exiba error.message e permita tentar novamente.

URLs dos arquivos

Os resultados normalmente usam o domínio de arquivos da APIMart. Se a transferência falhar, pode ser retornada uma URL CDN do provedor sem garantia de validade.
Baixe e armazene o arquivo rapidamente. Não use uma URL temporária como armazenamento permanente.

Erros

Erros de validação retornam HTTP 400 antes da criação e cobrança. HTTP 403 com model_price_not_configured significa que o preço suno@download não está configurado; contate o suporte.

Cobrança e downloads repetidos

  • Uma solicitação com vários formatos gera uma cobrança
  • Reenviar a mesma música gera nova cobrança, mesmo no mesmo formato
  • Solicitar outro formato em uma nova tarefa também gera cobrança
  • Tarefas com falha são reembolsadas automaticamente
Reutilize URLs já recebidas e desative o botão durante a solicitação para evitar envios e cobranças duplicadas.

Migração da API antiga

A API antiga permanece temporariamente disponível, mas todo novo código deve usar /generations/download.

Response

integer
Código de resposta; 200 em caso de sucesso
array
Dados da resposta de envio