API de download Free2

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

Descrição do endpoint

Free2 é um canal de download pago separado: resolve ficheiros MP3/WAV/letra/metadados a partir de um ID de música (ou de um link de música do suno.com) e devolve endereços de download alojados na plataforma. Aceita apenas uma chave de API — não aceita sessão de navegador — e a resposta nunca contém a origem de reprodução encriptada do Suno.

Endpoint: POST /api/music/free2

Cobrança: cobrado por música resolvida com sucesso, atualmente 0,2 CNY por música por defeito. Escolher vários tipos de ficheiro num pedido não custa mais; músicas que não se resolvem não são cobradas. No máximo 10 músicas por pedido (após desduplicação); o valor realmente debitado segue a configuração de preços do back-office.

Modelo recomendado: suno-v6. suno-v6, suno-v6-wild e suno-v6-mini estão disponíveis.

Autenticação

Parâmetros da requisição

Indique pelo menos um de song_id e song_ids; indique pelo menos um elemento em files.

Exemplo de requisição

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

Resposta

{
  "code": 200,
  "message": "success",
  "data": {
    "songs": [
      {
        "song_id": "song_id_1",
        "files": [
          {"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
        ]
      },
      {
        "song_id": "song_id_2",
        "files": [],
        "error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
      }
    ],
    "requested_songs": 2,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

Quando se pede apenas uma música, a resposta devolve também song_id e files no nível superior, por compatibilidade com a forma antiga de música única.

Reutilizar endereços em cache (sem custo)

Para uma música que já descarregou antes, voltar a descarregar não precisa de nova resolução nem volta a ser cobrado: use POST /api/music/free2/cached para obter os endereços atuais dos ficheiros que esta conta descarregou antes.

Endpoint: POST /api/music/free2/cached

Cobrança: Grátis. É uma cache só de leitura: não resolve, não transcodifica e não cobra; devolve apenas endereços já preparados e não recolhidos.

⚠️ Validade do endereço de download: 7 dias — guarde a tempo. songs[].files[].url é servido pelo armazenamento de objetos da plataforma e expira por defeito após 7 dias (os ficheiros são recolhidos e o endereço antigo devolve 404); guarde-os no seu próprio armazenamento dentro desses 7 dias. Quando um endereço expirar, chame de novo POST /api/music/free2 para o preparar novamente e obter um endereço válido (essa re-preparação é cobrada pelas regras normais; /api/music/free2/cached só devolve endereços de cache ainda válidos).

Parâmetros da requisição: idênticos a POST /api/music/free2 (qualquer um de song_id / song_ids / songs, e pelo menos um elemento em files).

curl -X POST https://www.suno-api.io/api/music/free2/cached \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'

{
  "success": true,
  "data": {
    "items": [
      { "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
    ],
    "songs": [
      { "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
      { "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
    ],
    "missing": ["a185b3d9-…"]
  }
}

Só são devolvidos endereços para músicas que já descarregou antes; músicas sem registo de download, ou cujos ativos já foram recolhidos, aparecem apenas em missing e não devolvem qualquer endereço.

Observações

• POST /api/music/free2 pode resolver qualquer música pública do Suno (incluindo músicas que não estão nesta plataforma); quando uma música não se consegue resolver, é devolvido um error apenas para essa música e as restantes do mesmo lote não são afetadas. Já POST /api/music/free2/cached só devolve endereços de músicas que esta conta descarregou.
• A primeira resolução de uma música cria os ficheiros alojados, que depois são reutilizados; não passe tipos duplicados em files, o servidor desduplica automaticamente.
• Diferença em relação à API de download e pré-visualização de mídia de músicas: a Free2 é paga, permite passar links do suno.com diretamente e não oferece tipos como linha do tempo/MIDI além da letra.