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

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 é válida, mas não pode executar a requisição — quase sempre por saldo insuficiente. Recarregue a conta e repita a mesma requisição.

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

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

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

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

Troque a chave quando necessário

Se houver suspeita de vazamento, crie uma substituta e apague a antiga. Trocar é barato; uma chave exposta não é.

Limite de requisições

As requisições são limitadas por chave. Ao exceder o limite a API retorna 429 Too Many Requests.

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 uma sequência aleatória. Trate o valor inteiro como um único token.

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?

Várias. Use uma por aplicação ou ambiente para revogá-las de forma independente.

As chaves expiram?

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

Como acompanho o uso?

Saldo e histórico ficam no console. Cada geração custa ¥0,6 e devolve duas faixas; falhas são reembolsadas automaticamente.

Páginas relacionadas

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