API de upload e cover em uma etapa

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

Descrição do endpoint

Upload e cover em uma etapa envia um arquivo de áudio ou uma URL de áudio e gera uma nova versão de cover a partir desse áudio de origem.

Endpoint: POST /api/music/upload-cover

Cobrança: Pago, atualmente ¥0,6 por chamada por padrão. Este endpoint é "enviar e fazer o cover" — não se trata de enviar uma capa de imagem. O valor realmente cobrado segue a configuração de preços atual do back-office.

Max Mode / Variety: este endpoint aceita os parâmetros opcionais max_mode e variety (0-4). Com max_mode ligado, esta chamada é cobrada em 2× o preço (0,6 → 1,2 ¥ por chamada); variety não custa nada a mais. O que significam e como enviá-los está na seção "Parâmetros avançados" da Visão geral da nova API.

Tempos de espera e timeouts (importante): este é um endpoint síncrono — o pedido só é aceito e entregue à geração quando a resposta chega. Pelo medido, a maioria das requisições responde em 1-3 segundos, cerca de 10% leva mais de 30 segundos e a mais longa fica em torno de 230 segundos. Defina o timeout do cliente em 300 segundos ou mais; não receber resposta não significa que nada foi gerado, e não repita logo após um timeout (isso duplica o pedido e cobra de novo). Se a conexão caiu, confirme depois com GET /api/music/songs. Veja "Tempos de espera e configuração de timeout" na Visão geral da nova API.

Quando o áudio é grande, convém separar "envio" e "cover" em duas etapas (recomendado)

Este endpoint exige que todo o áudio vá no corpo da requisição: quanto maior o áudio, maior o corpo, e uma oscilação de rede ou um timeout corta a transferência pela metade, e então o servidor devolve unexpected end of JSON input (HTTP 400, sem cobrança).

Quando o áudio passa de cerca de 8 MB, a rede é instável ou o mesmo material de origem será reutilizado, mude para a forma em duas etapas:

1. POST /api/music/upload-source envia primeiro o áudio de origem — grátis, pode repetir a qualquer momento — e devolve um clip_id;
2. POST /api/music/generate-from-source inicia o cover com esse clip_id — o corpo da etapa cobrada tem apenas cerca de 250 bytes.

Veja a API de upload de áudio de origem, a API de cover a partir de um clip de origem e "Arquivos grandes e requisições truncadas" no fim desta página.

Parâmetros da requisição

Headers

Parâmetros do body

cover_start_s e cover_end_s estão em segundos e aceitam decimais; o tempo inicial deve ser menor que o final e não pode passar da duração do áudio de origem. Se os dois campos forem omitidos, usa-se o áudio inteiro. audio_weight é mapeado para o metadata.control_sliders.audio_weight do Suno e controla o quanto o resultado se apoia no áudio de referência; assume 0.0-1.0 e só pode ser incluído quando a requisição traz um áudio de referência válido em file_url ou file_base64. 0 é um valor válido; omitir o campo significa "não especificado" e mantém o comportamento padrão do Suno. instrumental e waitAudio devem ser booleanos JSON, não strings.

O endpoint de upload devolve de forma assíncrona por padrão. Enquanto clips[].status na resposta for pending, um audio_url vazio é normal e não significa que o upload ou o cover falharam; guarde o song_id real devolvido e consulte o endpoint de consulta de músicas até terminar antes de ler o endereço do áudio.

Exemplo de requisição

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Nova letra ou direção da adaptação",
    "style": "Mandopop, acoustic guitar",
    "title": "Versão cover",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Resposta

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Versão cover",
        "status": "pending"
      }
    ]
  }
}

Arquivos grandes e requisições truncadas

Recomendado: dividir upload e cover em duas etapas

O endpoint de uma só vez (este) junta upload e geração numa única etapa: o corpo grande fica nessa única etapa, então quando ele quebra você não sabe se algo foi gerado nem se houve cobrança.

Conclusão: áudio acima de cerca de 8 MB, rede instável ou o mesmo material usado várias vezes → use a forma em duas etapas; áudio pequeno em rede estável → este endpoint dá menos trabalho.

O que significa 400 unexpected end of JSON input

Significa que o JSON que o servidor recebeu está incompleto (não é parâmetro errado, nem problema de permissão ou saldo). As causas comuns, da mais provável para a menos:

1. Um corpo grande truncado no meio da transferência: a camada de entrada registra tanto "quantos bytes o cliente declarou" quanto "quantos chegaram de fato". Caso medido: o cliente declarou 14,17 MB e chegaram apenas 11,8–12,4 MB, e as três requisições pararam por volta de 1,6–1,7 s; a quantidade de bytes faltantes era diferente a cada vez, o que indica corte de transferência e não um limite fixo (o servidor não limita o tamanho do corpo).
2. Content-Length diferente dos bytes realmente enviados: no Node.js, usar o .length de uma string (contagem de caracteres UTF-16) como comprimento erra sempre que o conteúdo tem chinês ou outro texto multibyte.
3. Escrever o corpo como string em vez de Buffer, de modo que os bytes escritos não batem com o declarado.

Os três casos acontecem antes da cobrança, então nenhum valor é gerado.

Lista de autoverificação do cliente

• O Content-Length vem de Buffer.byteLength(json, 'utf8') (ou Buffer.from(json).length) — nunca de json.length;
• O corpo da requisição é escrito como Buffer, não como string;
• O timeout do socket / da requisição é ≥ 300 segundos;
• Quando o áudio passa de cerca de 8 MB: use file_url (o corpo tem só algumas centenas de bytes), ou o upload multipart do upload-source, ou vá direto para a forma em duas etapas;
• Em requisições multipart, não defina Content-Type manualmente (deixe o cliente incluir o boundary);
• Imprima os "bytes realmente enviados" e compare com o Content-Length;
• Na forma em duas etapas, confirme que a etapa 1 devolveu um clip_id com status concluído antes de enviar a etapa 2.

Erros frequentes

Endpoints relacionados: API de upload de áudio de origem (etapa 1), API de cover a partir de um clip de origem (etapa 2).