Autenticação

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

Todas as requisições à Suno-API são autenticadas com uma chave de API. Esta página cobre como criar a chave, como enviá-la, o que os erros significam e como manter a chave segura.

O que é uma chave de API

A chave é um token bearer ligado à sua conta. Ela carrega o saldo, então quem tiver a chave pode gastá-lo. A chave é exibida apenas uma vez na criação: copie e guarde em local seguro.

Criando uma chave

1. Cadastre-se em https://www.suno-api.io — basta um e-mail, sem número de telefone.
2. Abra o gerenciamento de tokens no console.
3. Crie uma nova chave e copie.

As chaves têm o formato sk-…. Uma chave perdida não pode ser recuperada: crie outra e apague a antiga.

Usando a chave

Formato do cabeçalho

Envie a chave no cabeçalho Authorization em toda requisição:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Exemplo

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 peça de piano calma para um café"}'

Erros de autenticação

401 Unauthorized

O cabeçalho está ausente, malformado ou a chave não existe.

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

Confira se o cabeçalho está exatamente como Bearer <chave> (com espaço após Bearer) e se não entrou uma quebra de linha no fim da chave.

403 Forbidden

A chave existe, mas não tem permissão para esta requisição — quase sempre porque a chave foi desativada ou a conta está suspensa. Verifique o estado da conta no console e fale com o suporte se o motivo não for evidente.

Boas práticas de segurança

Nunca coloque a chave no código do cliente

Não embuta a chave em páginas web, aplicativos móveis ou binários de desktop. Quem conseguir abrir o inspetor do navegador pode lê-la e gastar o seu saldo. Chame a API do seu próprio servidor e exponha o seu endpoint aos usuários.

Use variáveis de ambiente

Linux / macOS

# ~/.bashrc ou ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

.env

# arquivo .env — inclua no .gitignore
SUNO_API_KEY=sk-your-key-here

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

Troque a chave quando necessário

Troque as chaves a cada 3-6 meses e imediatamente se suspeitar de vazamento. Apague as chaves que não usa mais: uma chave parada é apenas um risco parado.

Limite de requisições

As requisições são limitadas por chave:

429 Too Many Requests

Ao ultrapassar um limite a API devolve 429 e a resposta pode trazer um valor retry_after em segundos. Espere esse tempo antes de tentar de novo; reduza o ritmo de requisições, enfileire o trabalho ou repita com backoff exponencial em vez de em laço apertado.

Política de repetição

Repita apenas em falhas explícitas. Não repita após timeout de leitura ou de conexão: os endpoints de geração são síncronos, então um timeout pode significar que o pedido já foi aceito e está sendo gerado — repetir cria um pedido duplicado e cobra duas vezes. Defina o timeout do cliente em 300 segundos ou mais e, após uma conexão caída, confirme o pedido com GET /api/music/songs antes de reenviar. Veja "Tempos de espera e configuração de timeout" na Visão geral da nova API.

Reenvie com backoff exponencial em vez de em um laço apertado:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

Perguntas frequentes

Qual é o formato da chave?

Começa com sk- seguido de letras e dígitos, cerca de 50-60 caracteres no total.

Posso chamar a API direto do navegador?

Tecnicamente sim, mas não faça isso em produção: a chave ficaria visível a todos os visitantes. Faça proxy pelo seu backend.

Como sei se a chave ainda é válida?

Envie qualquer requisição autenticada. 200 indica que funciona; 401 indica chave inválida ou apagada.

Perdi a chave. E agora?

Chaves não são recuperáveis. Crie uma nova no console e apague a antiga.

Quantas chaves uma conta pode ter?

Não há limite fixo. Use uma chave por aplicação ou ambiente para poder revogá-las separadamente e apague as que deixar de usar.

As chaves expiram?

Valem até você apagá-las ou encerrar a conta. Trocar periodicamente é boa prática.

Como acompanho o uso?

Entre no console: lá aparece o uso por chave, com número de requisições, gasto e tarefas recentes.

Páginas relacionadas

• Guia de início rápido
• Modelos compatíveis