API de download e pré-visualização de mídia de músicas

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

Descrição do endpoint

Este grupo de endpoints separa "obter um endereço de mídia" de "baixar o arquivo de fato":

• Para obter um endereço que você possa reproduzir ou baixar diretamente (por exemplo, para colocar no seu próprio player ou copiar para um armazenamento de objetos): use POST /api/music/download-url, ou o GET /api/music/download que já vem nas respostas.
• Para o navegador salvar o arquivo em disco: use POST /api/music/download-file (arquivo único) ou POST /api/music/download-all (pacote).
• Se a música ainda está sendo gerada e você quer ouvir antes: use POST /api/music/generation-stream-url.

Cobrança: Tudo grátis. Download e pré-visualização apenas leem mídia que a plataforma já hospeda; não chamam o Suno e não geram cobrança.

Modelo recomendado: suno-v6. Você pode usar suno-v6, suno-v6-wild ou suno-v6-mini.

Autenticação

Tipos de mídia suportados (kind)

1) Obter um endereço de mídia

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url serve para reproduzir ou copiar por conta própria; nav_url traz Content-Disposition: attachment, o que permite colar direto na barra de endereços do navegador para baixar (útil quando alguns navegadores móveis não suportam download por blob).

⚠️ Validade do endereço: 7 dias — copie o arquivo a tempo

url / nav_url apontam para o armazenamento de objetos da plataforma e expiram por padrão após 7 dias (os arquivos são recuperados e o endereço antigo devolve 404). Copie os arquivos para o seu próprio armazenamento dentro desses 7 dias.

Depois de expirar, não é preciso gerar a música de novo: basta chamar POST /api/music/download-url novamente (ou passar refresh: true) para obter endereços novos e válidos dessa música. Este grupo de endpoints é gratuito e não acrescenta cobrança.

2) Baixar um único arquivo diretamente

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": "song_id", "kind": "song"}' \
  -o song.mp3

O corpo da resposta é um fluxo de arquivo (não JSON) e o Content-Disposition já traz o nome do arquivo. A letra e a letra com marcas de tempo só podem ser obtidas com este endpoint (o download-url devolve apenas endereços de mídia, não a letra). O arquivo .lrc atualmente só é suportado em algumas músicas; se devolver success:false, gere o .lrc você mesmo com a API de letras com marcas de tempo conforme a próxima seção, e não repita a chamada.

Como obter letras com marcas de tempo (.lrc)

Recomendamos dois passos, que servem para qualquer música:

Passo 1: obter a linha do tempo palavra por palavra (grátis)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

A resposta é um array direto (sem invólucro data); cada elemento tem a forma {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. O word já contém quebras de linha, então dá para separar por linha; para o significado dos campos, o filtro de trechos instrumentais e outras ressalvas veja os "Campos" e as "Notas de uso" da API de letras com marcas de tempo.

Passo 2: montar o .lrc você mesmo a partir de start_s (formato de tempo [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc também baixa diretamente o .lrc gerado pelo servidor, mas atualmente só algumas músicas são suportadas: se devolver success:false, gere você mesmo como acima — não é preciso repetir a chamada e a cobrança não é afetada.

3) Download em pacote

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_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

Use song_id (um único) ou song_ids (lote, até 50 itens). O corpo da resposta é um fluxo ZIP.

4) Endereço de download estável

GET /api/music/download?song_id=<id>&kind=<kind> é o ponto de entrada de download que aparece diretamente nas respostas de música. Aceita tanto uma chave de API quanto uma sessão de navegador, tem o mesmo comportamento do download-file e é adequado para fixar em um cliente ou player de terceiros.

5) Pré-escuta durante a geração

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

Um playable_until_completed igual a true indica um endereço temporário de pré-escuta de uma música em geração; troque pelo endereço definitivo quando a música terminar. Se uma música falhar, esse item traz um campo error e as demais são devolvidas normalmente.

Observações

• Todos os endpoints devolvem apenas endereços de mídia hospedados pela plataforma; nunca devolvem a fonte criptografada do Suno nem um endereço assinado temporário.
• Os endereços não são permanentes: copie os arquivos você mesmo se precisar guardá-los a longo prazo; use download-file quando precisar do arquivo original em disco.
• O MIDI de um stem exige que a separação desse stem tenha terminado; caso contrário, é devolvido um erro.