Autenticação

Toda chamada de API que cria, consulta ou cobra algo envia sua chave de API no cabeçalho Authorization. A única exceção é o catálogo público de modelos usado para avaliação, que não exige chave.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A API nativa (/api/v1/*) aceita somente chaves Bearer, sem cookies nem parâmetros de consulta.

Os endpoints de compatibilidade de texto e vídeo (/v1, /v1beta) usam a mesma chave e também aceitam o cabeçalho x-api-key usado pelos SDKs da Anthropic e o x-goog-api-key usado pelos SDKs Google GenAI. Assim, os SDKs oficiais funcionam alterando apenas a URL base; veja Texto e streaming. Esses dois cabeçalhos não têm efeito em /api/v1, e nenhum endpoint aceita uma chave nos parâmetros de consulta da URL.

Chaves de API e console são separados

Somente /api/v1, /v1 e /v1beta aceitam chaves de API. O console web usa sua própria sessão de navegador. Portanto, o login do console não pode ser usado como chave de API, e uma chave de API vazada não permite entrar no console. Enviar o tipo errado de credencial sempre retorna 401, nunca um erro de permissão.

Formato de uma chave

Um prefixo fixo sk-spicy-, seguido de 48 caracteres hexadecimais minúsculos.

O prefixo é intencional: é melhor que um sistema encontre a chave e avise você do que descobrir o vazamento quando outra pessoa já estiver gastando seu saldo.

Criar uma chave

1. Abra Console → Chaves de API e clique em Criar chave.
2. Dê um nome que identifique o serviço que usará a chave, como production backend ou staging worker. Você precisará reconhecê-la ao revogá-la.
3. Se desejar, abra Avançado para definir limites de gastos, uma lista de modelos permitidos, uma lista de IPs permitidos e uma data de expiração. Todos esses ajustes podem ser alterados depois.
4. Copie a chave ou clique em Salvar como arquivo e confirme que a guardou. Depois que a janela fechar, a chave não poderá ser exibida novamente.

Para criar chaves, é necessário ter o papel de proprietário, administrador ou desenvolvedor na equipe. A chave pertence à equipe selecionada no canto superior esquerdo do console: seu uso e seus limites contam para essa equipe. Cada equipe pode ter até 50 chaves ativas. Sua conta também precisa de e-mail verificado e saldo para a chave executar operações pagas; veja Configuração da conta.

Onde guardar a chave

• No seu computador, para testes: use export SPICY_API_KEY="…" no terminal, válido até fechar a janela, ou um arquivo .env carregado pelo seu código. Adicione .env a .gitignore antes do primeiro commit.
• Em um servidor ou plataforma de hospedagem: use as configurações de segredos ou variáveis de ambiente e leia SPICY_API_KEY do ambiente no seu código.
• Nunca cole a chave em código-fonte, conversas, capturas de tela, chamados de suporte ou prompts de assistentes de IA.

Nunca distribua uma chave no cliente

A mesma regra vale para binários de aplicativos móveis, clientes desktop, notebooks públicos, logs de CI e qualquer conteúdo que acabe em uma saída de curl -v colada em um chamado de suporte.

Suas próprias ferramentas no seu próprio navegador são um caso diferente. A API aceita chamadas de navegadores; por isso, ferramentas de uso pessoal nas quais você informa sua própria chave, como a extensão do SillyTavern ou um aplicativo de roleplay, podem chamá-la diretamente. A regra acima trata de incluir uma chave em algo que outras pessoas carregam. Dê a cada ferramenta uma chave própria com limite diário, para acompanhar seus gastos e revogá-la separadamente.

Restrições por chave

Configure-as no console ao criar a chave ou depois. Elas são aplicadas no servidor.

O cartão de cada chave mostra os limites atuais, que você pode alterar ali a qualquer momento.

Os limites incluem tanto o dinheiro reservado para tarefas em execução quanto o já gasto; uma chave pode atingir o limite enquanto há tarefas em andamento. O msg informa qual limite foi atingido. Um 40202 cujo msg menciona a cota da plataforma não se refere à sua chave: criar outra não resolve; tente mais tarde.

A lista de IPs permitidos é comparada com seu endereço público real, conforme visto pela nossa rede de borda, não com o endereço do último proxy. Seu endereço de saída é o IP público de onde partem as solicitações do servidor: a maioria das plataformas de hospedagem o informa nas configurações de rede; no seu computador, curl https://ifconfig.me o mostra.

Tarefas pertencem à chave que as criou

Uma tarefa só fica visível pela API para a chave de API que a criou. Com qualquer outra chave, mesmo da mesma equipe:

Duas coisas não ficam vinculadas à chave. Os webhooks de uma tarefa são entregues mesmo após a revogação da chave que a criou. Além disso, todas as tarefas da equipe, independentemente da chave usada, aparecem em Console → Logs, e os detalhes de cada tarefa mostram a Chave usada.

Rotação

• Uma chave por ambiente, produção, testes e local, para revogar uma sem afetar as outras.
• Rotação planejada: crie a nova chave e envie somente tarefas novas com ela. Mantenha a antiga ativa até que todas as tarefas criadas por ela atinjam um estado final, no máximo até o deadlineAt de cada tarefa, e você tenha coletado os resultados; depois, revogue-a. Use essa sequência somente se a chave antiga ainda for confiável.
• A revogação é imediata e irreversível. Não há cache para esperar expirar nem possibilidade de reativar a chave; você precisa criar outra.

Depois de um vazamento

Se houver gastos inesperados, entre em contato em Console → Suporte, informando os IDs das tarefas ou os valores de request_id.

Como é uma falha de autenticação

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

O status HTTP também é 401. Toda falha de autenticação retorna code: 401, e msg informa o tipo:

Baseie a lógica em code, não no texto: a redação pode mudar e segue seu idioma de erros. Veja mais sobre essas diferenças em Erros.

Quando a própria conta não pode chamar a API, por e-mail não verificado ou conta suspensa, você recebe 403. Trocar a chave não resolve esse caso.