API de cover a partir de um clip de origem

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

Descrição do endpoint

O cover a partir de um clip de origem reutiliza um clip de origem que você já enviou, ou que já existe, e gera a partir dele uma nova versão de cover.

Endpoint: POST /api/music/generate-from-source

Cobrança: Pago, atualmente ¥0,6 por chamada por padrão. Enviar o áudio de origem em si é gratuito; a cobrança acontece ao gerar um cover a partir do clip de origem. 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.

Uso recomendado: é o passo 2 do «cover em duas etapas». No passo 1, envie com a API de upload de áudio de origem (grátis) e guarde o clip_id; no passo 2, chame este endpoint para iniciar o cover. Assim o áudio só aparece na etapa gratuita: se o envio falhar, basta tentar de novo e nada é cobrado, enquanto o corpo da requisição da etapa cobrada tem apenas algumas centenas de bytes, então dificilmente falhará por causa de um transporte interrompido. A API de upload e cover em uma etapa coloca o áudio inteiro no corpo da requisição, então assim que o áudio passa de cerca de 8 MB ele tende a ser truncado em trânsito e a retornar unexpected end of JSON input (veja "Arquivos grandes e requisições truncadas" naquela página).

Além disso, o mesmo clip_id pode ser reutilizado para Extend, Replace Section, separação e outras ações seguintes, sem precisar enviar o áudio de novo.

Parâmetros da requisição

Headers

Parâmetros do body

weirdnessConstraint, styleWeight e audio_weight usam um decimal de proporção de 0.0 a 1.0, não um inteiro de porcentagem; por exemplo, 50% é 0.5. 0 é um valor válido; só omitir o campo significa "não especificado". 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; só pode ser incluído quando a requisição traz um sourceClipId válido ou um áudio de referência, então não o envie numa geração comum só de texto. Com customMode=true, escreva a letra nova em prompt e forneça style e title juntos; com customMode=false, escreva a descrição criativa em prompt. instrumental e waitAudio devem usar os booleanos JSON true/false.

Este endpoint devolve de forma assíncrona por padrão. Enquanto o status devolvido for pending, um audio_url vazio é normal; espere terminar antes de usar o endereço do áudio. sourceClipId deve ser um ID real de música/clip de origem: não use um task_id, um client_request_id nem um ID de preenchimento pending:.

Que tipo de ID é sourceClipId

sourceClipId é o identificador real de clip do Suno usado como origem deste cover. O objeto de música de cara ao cliente da plataforma costuma nomear esse identificador como song_id, enquanto os parâmetros da requisição de cover mantêm o nome sourceClipId; aqui os dois significam o mesmo ID real de música.

Se a origem for um upload reforçado, consulte primeiro a tarefa de upload reforçado e espere o status virar completed; depois coloque o song_id real devolvido em sourceClipId. Recomenda-se colocar também o audio_url e o title desse resultado em sourceAudioUrl e sourceTitle.

Não coloque o task_id, o client_request_id nem um ID de preenchimento pending:enhanced-upload:* do upload reforçado em sourceClipId.

Exemplo de requisição

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "Título do áudio original",
    "prompt": "Nova letra ou direção criativa",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "Título do cover",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

Resposta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Título do cover",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

Observações

Este endpoint tenta resolver a qual conta o clip de origem pertence. Se o clip de origem não puder ser usado diretamente, o servidor pode enviá-lo de novo com base nas informações do áudio de origem e só então gerar.