API de Replace Section (substituição de trecho)

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

Descrição do endpoint

O Replace Section regenera no lugar um intervalo de tempo de uma música existente. Serve para corrigir uma linha da letra ou trocar um trecho.

Endpoint: POST /api/music/replace-section

Cobrança: Pago, atualmente ¥0,6 por chamada por padrão. 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.

Parâmetros da requisição

Headers

Parâmetros do body

startSeconds e endSeconds estão em segundos e aceitam decimais; startSeconds deve ser menor que endSeconds e o intervalo deve ficar dentro da duração da música original. requestedAt só é usado quando você precisa enviar o horário da requisição, como timestamp Unix em segundos (não milissegundos); normalmente pode ser omitido.

A substituição também é uma tarefa assíncrona. O clip devolvido pode começar em pending, e o endereço de áudio vazio nesse momento é normal; use o song_id real devolvido para consultar o resultado final.

Comprimento do trecho: pelo menos 2 segundos (importante)

O intervalo a substituir não pode ser menor que 2 segundos. Medido: intervalos de 1,0 / 1,2 / 1,5 segundo falharam todos, enquanto 2,0 segundos ou mais funcionaram.

Quando o intervalo é curto demais, a plataforma não responde com um "erro de parâmetro", mas com uma mensagem fácil de interpretar mal:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

Essa frase não é problema de conta nem de plano — o trecho é curto demais. Alongue o intervalo para mais de 2 segundos e envie de novo.

Exemplo de requisição

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "letra completa de contexto",
    "contextWindowLyrics": "letra de contexto da janela",
    "infillLyrics": "letra da substituição",
    "style": "Mandopop, acoustic",
    "title": "Versão substituída",
    "negativeTags": "noise"
  }'

Resposta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Versão substituída",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Campos compatíveis

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags