Skip to main content
POST
Referenciar faixa de origem: operações baseadas em músicas existentes não exigem memorizar nenhum id adicional, basta passar task_id (o task_id da tarefa que gerou a faixa de origem) + audio_index (qual música dentro de music[] do resultado, baseado em 1, padrão 1).
custom determina quais campos têm efeito: campos preenchidos no modo errado são silenciosamente ignorados (sem erro). Com custom=true, prompt (letra), title, tags, negative_tags, auto_lyrics, style_weight, weirdness_constraint e audio_weight têm efeito e gpt_description é ignorado; com custom=false, apenas gpt_description é lido (obrigatório nesse caso — se faltar, um 400 é retornado no envio). vocal_gender funciona em ambos os modos. Se custom não for informado, o backend o infere nesta ordem: prompt presente → true; sem prompt mas com gpt_description presente → false; caso contrário, tags/title presente → true.

Authorizations

string
obrigatório
Todos os endpoints exigem autenticação com Bearer TokenObter a API Key:Acesse a página de gerenciamento de API Key para obter sua API KeyAo usar, adicione ao cabeçalho da requisição:

Body

string
padrão:"suno"
Modelo de áudio. Atualmente passe suno (se não informado, o padrão é suno).
string
obrigatório
O task_id da tarefa que gerou a faixa de origem (normalmente uma amostra enviada). Se estiver ausente ou se a origem não puder ser resolvida, um 400 é retornado no momento do envio.
integer
padrão:"1"
Qual música dentro de data.music[] do resultado da tarefa de origem (começa em 1: 1 = primeira música; padrão 1; uma geração normalmente produz 2 músicas: índices 1 e 2).
number
obrigatório
Ponto inicial da amostragem (segundos). Se faltar, retorna 400 imediatamente.
number
obrigatório
Ponto final da amostragem (segundos). Se faltar, retorna 400 imediatamente.
boolean
padrão:"false"
Se é puramente instrumental (true=sem vocais). Se não informado, o padrão é false (com vocais).
string
padrão:"v5.5"
Versão de geração: v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, afeta a qualidade do áudio e a cobrança; padrão v5.5 se omitido, e um valor inválido retorna 400 diretamente no envio.
boolean
true=modo personalizado (prompt usado como letra); false=modo inspiração (usa gpt_description); se não informado, é inferido a partir do conteúdo (veja o aviso acima).
string
Letra. Tem efeito quando custom=true (ignorado no modo inspiração).
string
Prompt de inspiração. Obrigatório quando custom=false — se faltar, a requisição falha com 400 no envio (nada é cobrado).
string
Título. Só tem efeito quando custom=true.
string
Tags de estilo. Só tem efeito quando custom=true.
string
Tags de estilo a excluir. Só tem efeito quando custom=true.
boolean
true=reescreve a letra fornecida de forma criativa. Só tem efeito quando custom=true.
number
Peso do estilo, 0.001.00 (valores fora do intervalo retornam 400 diretamente no envio). Só tem efeito quando custom=true.
number
Peso de criatividade, 0.001.00 (alias weirdness). Só tem efeito quando custom=true.
number
Peso de áudio, 0.001.00. Só tem efeito quando custom=true.
string
Gênero vocal: Male / Female. Funciona em ambos os modos.
Obter resultado: este endpoint é uma tarefa assíncrona. Após enviar, você recebe task_id; faça polling em GET /v1/music/tasks/{task_id} a intervalos de 3–5s, até que status seja completed ou failed (a geração de música normalmente leva 30–120s; durante a geração, status é pending e progress vai de enfileirado 10 → pronto 50 → concluído 100). Ao concluir, pegue audio_url em data.result.music[]. Em caso de falha, data.error.message indica o motivo e a cota pré-deduzida é automaticamente devolvida.

Response

integer
Código de status da resposta
array
Array de dados retornados