Guia de início rápido

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

Este guia leva você da criação da chave de API até a primeira música gerada, a consulta de progresso e o download do áudio em cerca de cinco minutos. Os exemplos podem ser copiados e executados como estão.

O modelo padrão atual é suno-v6. Os modelos de geração de suno-v2 a suno-v5-5 foram desativados: podem aparecer em tarefas antigas, mas não aceitam novas requisições.

Passo 1: obter uma chave de API

1. Acesse https://www.suno-api.io.
2. Clique em Obter chave de API e cadastre-se. Basta um e-mail, sem número de telefone.
3. No console, abra o gerenciamento de tokens e crie uma chave.
4. Copie imediatamente — a chave é exibida uma única vez. Recarregue o saldo com um código de resgate antes da primeira chamada paga.

Passo 2: configurar a requisição

Todas as chamadas usam a mesma URL base e os mesmos cabeçalhos:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Passo 3: enviar a primeira requisição

Exemplo 1 — gerar a partir de uma linha de descrição

Descreva a música e a API escreve letra, melodia e arranjo:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "uma canção folk animada sobre o primeiro dia de primavera",
    "model": "suno-v6"
  }'

Resposta:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "História de Primavera",
    "description": "uma canção folk animada sobre o primeiro dia de primavera",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Passos da Primavera",
    "description": "uma canção folk animada sobre o primeiro dia de primavera",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Cada execução devolve duas versões diferentes para você escolher. Uma geração custa ¥0,6.

Exemplo 2 — consultar o progresso

Envie os song_id retornados para o endpoint de consulta:

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": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Enquanto a tarefa roda:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "História de Primavera",
    "progress": "60%"
  }
]

Quando termina:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "História de Primavera",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

O status passa por pending, submitted, processing e chega a completed. Os endereços podem ficar vazios durante a execução: avalie pelo status, não pela presença de audio_url.

Passo 4: baixar o arquivo

Quando o status for completed, basta requisitar o audio_url. Os downloads em MP3 e WAV são ilimitados e não custam extra. Se precisar de áudio sem perdas para edição, use o endpoint de WAV.

Cenários comuns

Trilha de fundo para vídeo

{
  "description": "trilha lo-fi calma para vídeo de produto, sem vocais, dinâmica estável",
  "instrumental": true,
  "model": "suno-v6"
}

Com instrumental em true a saída não tem vocais.

Letra e estilo próprios

{
  "lyrics": "[Verse 1]\nAs luzes da cidade vão sumindo\n\n[Chorus]\nSeguimos andando",
  "style": "acoustic pop, vocal feminino caloroso, 92 BPM",
  "model": "suno-v6"
}

Consultando até concluir

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "uma canção folk animada sobre a primavera", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Tratamento de erros

Principais códigos

Formato do erro

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Boas práticas

• Mantenha a chave no servidor, nunca no navegador ou em apps distribuídos.
• Consulte a cada 10–15 segundos em vez de em laço apertado.
• Guarde os song_id: são o único identificador para recuperar o áudio depois.
• Reenvie em 429 e 500; corrija a causa antes de reenviar 400 e 401.
• Falhas são reembolsadas automaticamente, então uma tarefa malsucedida não custa nada.

Próximos passos

• Autenticação — chaves, erros e limites
• Modelos compatíveis — nomes de modelo, stems e modelos desativados