API de separação (voz e acompanhamento)

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

Descrição do endpoint

A separação divide uma música existente em voz, acompanhamento ou resultados multipista. O fluxo de integração recomendado é:

1. Se o áudio de origem não for uma música gerada nesta plataforma, chame primeiro a API de upload de áudio de origem.
2. Chame POST /api/music/separate para enviar a tarefa de separação.
3. Consulte o resultado com a API de consulta e histórico de músicas.
4. Use os endpoints de download para baixar o arquivo de áudio de cada resultado de separação.

Endpoint: POST /api/music/separate

Cobrança: Pago. stem_mode=two atualmente ¥0,6 por chamada por padrão; stem_mode=twelve é um split multipista e atualmente ¥3,0 por chamada por padrão. O valor realmente cobrado segue a configuração de preços do back-office.

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.

Autenticação

Parâmetros da requisição

Sobre stem_mode

Sobre a separação

A separação é um recurso fixo e independente: não é preciso preencher nem escolher um modelo de geração de músicas. O cliente apenas envia a música de origem e stem_mode; o servidor cuida do resto conforme o modo.

De onde vêm os números: um envio produz 2 versões (dois resultados do mesmo material), então o número é 2 × as faixas desse modo: 4 para two e 24 para twelve. Guie-se sempre pelo comprimento real do array clips na resposta; não escreva um laço com número fixo (alguma faixa pode falhar e as bem-sucedidas são devolvidas normalmente).

Quais faixas cada modo devolve

As 12 faixas do modo twelve (os nomes são fixados pela plataforma; a ordem pode variar):

O modo two devolve duas faixas, (Vocals) e (Instrumental), cada uma em 2 versões. Os títulos das faixas de two e twelve são nomes fixos (não trazem o nome da música de origem), então não espere descobrir de qual música se trata pelo título.

Os títulos das faixas não servem como chave única. Nas duas versões aparecem faixas com o mesmo nome (por exemplo duas (Vocals), duas (Strings)), e uma separação devolve muitas faixas. Use sempre song_id como identificador e song_title só para exibição; também não use índices do array (a ordem pode mudar).

Exemplos de requisição

Separação voz / acompanhamento (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Split multipista (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Resposta

Em caso de sucesso costuma ser devolvido um array de resultados de separação. Cada resultado é um clip de música independente e precisa continuar sendo consultado até que status passe a um estado concluído.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Acima são mostradas apenas 2 das 4 entradas do modo two; na prática são devolvidas 4 (2 versões × {(Vocals), (Instrumental)}); o modo twelve devolve 24. O número real é o comprimento do array clips.

Normalmente o cliente só precisa guardar clips[].song_id; as consultas e downloads seguintes giram em torno desses IDs.

Observações

• Os resultados de separação não aparecem no histórico de GET /api/music/songs (essa lista devolve apenas músicas geradas comuns). Após um envio bem-sucedido, guarde clips[].song_id imediatamente; caso contrário, depois não haverá como encontrá-los.
• Cada faixa é uma obra independente: cada faixa tem o seu próprio song_id e precisa ser consultada até concluir e baixada separadamente.
• A cobrança não depende do número de entradas: é cobrada por chamada (two ¥0,6 por chamada, twelve ¥3,0 por chamada), e 4 ou 24 entradas custam o mesmo.
• Download: use o song_id dessa faixa com POST /api/music/download-url / download-file (grátis), ou diretamente o audio_url do resultado da consulta; para MIDI veja a API de obtenção de MIDI.
• Não envie duas vezes: a separação é um endpoint síncrono, então após um timeout confirme primeiro com a consulta de músicas em vez de repetir logo (isso duplica o pedido e cobra de novo).
• Oculte faixas que já não precisa com a API de exclusão de stems.

Consultar os resultados de separação

Após um envio bem-sucedido, consulte os resultados com clips[].song_id via POST /api/music/query.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

Exemplo de consulta concluída:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Baixar arquivos de stems

Quando um resultado de separação está concluído, você pode baixar um arquivo de stem individual com o endpoint de download.

Endpoint: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind aceita:

Para empacotar os recursos relacionados de um resultado de separação, chame:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Descrição dos status

Erros comuns

Notas de compatibilidade

A documentação antiga usava exemplos de objeto único como success/task_id/vocals_url/instrumental_url. A separação atual baseia-se no array de músicas clips[]: cada resultado de separação tem o seu próprio song_id, e as consultas e downloads seguintes giram em torno desses song_id.

Páginas relacionadas

• Se só quer separar voz e acompanhamento sem escolher modo, use a API de remoção de voz; é a forma rápida de duas faixas deste endpoint e atualmente é grátis.
• Oculte faixas de separação que já não precisa com a API de exclusão de stems (exclusão lógica, sem cobrança).
• Para o MIDI de um stem veja a API de obtenção de MIDI; para áudio, capa e outros media, a API de download e pré-visualização de mídia de músicas.