PT ▾

Como testar uma chave de API de IA com curl e Python

Uma chave girando em uma fechadura com três luzes indicadoras verdes, representando um teste de chave de API bem-sucedido

Veja como testar o acesso à chave de API sem construir nada: três chamadas, cerca de dois minutos, e você saberá se a chave é válida, possui fundos e está autorizada a gerar texto.

Atualizado

Pontos principais

  • Chame GET /v1/models primeiro: isso prova que a chave é aceita sem gastar crédito.
  • Envie uma solicitação de chat curta para o modelo uncensored para confirmar que a geração funciona.
  • Leia o cabeçalho X-Balance-USD ou GET /v1/balance para ver o que resta.
  • 401 aponta para a chave, 402 para o saldo, 429 para a taxa de requisição.

O teste de três chamadas

Para testar uma chave de API de IA corretamente, você precisa provar três coisas separadas: o servidor aceita a chave, a chave tem crédito por trás e uma conclusão real é retornada. Uma chamada por pergunta mantém o diagnóstico simples. Se algo falhar, você saberá qual camada é a culpada.

  1. Lista de modelos. Autentica a chave e não custa nada.
  2. Chat completion. Confirma que o modelo responde e que o formato da sua requisição está correto.
  3. Saldo. Confirma o que restou após o teste.

Tudo abaixo usa a base URL https://api.aiapisource.com/v1 e o ID do modelo uncensored. Coloque sua chave em uma variável de ambiente para que ela nunca acabe no histórico do seu shell ou em um repositório.

export AIAPI_KEY="paste-your-key-here"

Se você ainda não tem uma chave, a página da chave de API mostra como criar uma. Contas novas podem resgatar um crédito de teste grátis de $0,50 com um clique, o que é mais do que suficiente para todos os testes neste artigo.

Passo 1: listar modelos com curl

A verificação mais barata é uma requisição somente leitura. GET /v1/models retorna a lista de modelos e requer uma chave válida, então uma resposta bem-sucedida prova a autenticação.

curl -s https://api.aiapisource.com/v1/models \
  -H "Authorization: Bearer $AIAPI_KEY"

Uma resposta saudável é JSON com uma matriz data que inclui uncensored. Se você vir uma página HTML, um erro de conexão ou uma resposta vazia, o problema é a URL, não a chave. Verifique se você manteve o sufixo /v1 e se não há espaço em branco após a chave na sua variável.

Adicione -i ao comando curl para ver os cabeçalhos da resposta. A API envia X-Request-Id em todas as chamadas. Mantenha esse valor se entrar em contato com suporte, pois ele identifica a requisição exata.

Passo 2: enviar uma solicitação de chat

Agora verifique a geração. Mantenha o prompt pequeno e limite a saída para que o teste custe uma fração de centavo.

curl -s https://api.aiapisource.com/v1/chat/completions \
  -H "Authorization: Bearer $AIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the single word: ready"}],
    "max_tokens": 10
  }'

Procure por choices[0].message.content e um objeto usage com prompt_tokens e completion_tokens. Uma requisição de aproximadamente 20 tokens de entrada e 5 tokens de saída custa 20 / 1.000.000 x $0,15 mais 5 / 1.000.000 x $0,50, o que dá cerca de $0,0000055. Você poderia executar uma centena desses por bem menos de um centavo.

O mesmo endpoint também funciona para streaming: adicione "stream": true e os tokens chegam como eventos enviados pelo servidor. Teste isso separadamente assim que a chamada básica funcionar.

Passo 3: o mesmo teste em Python

Se o seu código real usa um SDK OpenAI, teste também por meio do SDK. Ele captura problemas que o curl não detecta, como uma base URL passada para o argumento errado.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIAPI_KEY"],
    base_url="https://api.aiapisource.com/v1",
)

print([m.id for m in client.models.list().data])

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with the single word: ready"}],
    max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)

A primeira saída deve exibir uma lista contendo uncensored. A segunda mostra a resposta do modelo. Para um guia mais detalhado da configuração do SDK, consulte o guia da API OpenAI em Python deste site.

Execute a versão Python do mesmo shell onde você exportou a chave. Se ela levantar um KeyError em AIAPI_KEY, a variável não está definida nessa sessão, que é a razão mais comum de um teste falhar antes de chegar à rede.

Node funciona da mesma maneira: passe baseURL: "https://api.aiapisource.com/v1" e a chave para o construtor do cliente OpenAI.

Verificar o saldo

Uma chave pode ser válida e ainda não ter nada para gastar. Duas maneiras de ler o saldo:

curl -s https://api.aiapisource.com/v1/balance \
  -H "Authorization: Bearer $AIAPI_KEY"

# OpenAI-style alternative
curl -s https://api.aiapisource.com/v1/dashboard/billing/credit_grants \
  -H "Authorization: Bearer $AIAPI_KEY"

Toda resposta também carrega um cabeçalho X-Balance-USD, então a chamada de chat da etapa 2 já lhe disse o crédito restante se você a executou com -i. Em Python, o SDK OpenAI expõe isso através de client.chat.completions.with_raw_response.create(...), onde você lê response.headers["X-Balance-USD"].

Requisições falhas ou recusadas não são cobradas, então um teste que gera erro não consome crédito. O crédito pré-pago não expira, o que significa que um saldo não utilizado ainda estará lá na próxima semana.

Lendo os códigos de erro

Quando um teste falha, o status HTTP reduz rapidamente as possibilidades da causa.

CódigoSignificado usualO que fazer
401A chave está ausente, digitada incorretamente ou revogadaVerifique o cabeçalho Authorization: Bearer, copie a chave novamente, procure espaços ocultos ou aspas
402Sem crédito restante para pagar a solicitaçãoLeia o saldo, depois recarregue na página de preços
404Caminho errado ou ID de modelo erradoUse /v1/chat/completions e o modelo uncensored
429Limite de taxa ou concorrência, ou sobrecarga curtaAguarde e tente novamente; veja abaixo

Um 429 carrega um código de erro. rate_limited significa muitas requisições por minuto e concurrency significa muitas de uma vez. Uma chave completa permite 300 requisições por minuto e 8 requisições simultâneas; uma chave de teste permite 60 por minuto e 2 de uma vez. Em sobrecarga temporária, a API responde com 429 e Retry-After: 5, então aguarde cinco segundos e envie a requisição novamente. Uma requisição em streaming mantém seu slot de concorrência até que o streaming termine, o que é uma razão comum de uma chave de teste atingir o limite durante testes paralelos.

Os códigos de status 401, 402 e 404 seguem convenções normais de API, então trate a tabela como uma primeira suposição e leia o corpo de erro JSON para a mensagem exata.

Um script de smoke-test reutilizável

Depois que o teste manual passar, mantenha um script que você possa executar após rotacionar chaves ou alterar ambientes.

import os, sys
import requests

BASE = "https://api.aiapisource.com/v1"
H = {"Authorization": "Bearer " + os.environ["AIAPI_KEY"]}

m = requests.get(BASE + "/models", headers=H, timeout=15)
print("models", m.status_code)

c = requests.post(
    BASE + "/chat/completions",
    headers=H,
    json={"model": "uncensored",
          "messages": [{"role": "user", "content": "ping"}],
          "max_tokens": 5},
    timeout=60,
)
print("chat", c.status_code, "balance", c.headers.get("X-Balance-USD"))
sys.exit(0 if m.ok and c.ok else 1)

O código de saída facilita a integração em uma verificação de deploy. Para parâmetros além deste mínimo, a documentação da API lista tudo que o endpoint aceita.

Perguntas e respostas

Testar uma chave de API custa dinheiro?

A lista de modelos é gratuita para consultar. Uma solicitação de chat curta com max_tokens baixo custa alguns milionésimos de dólar a $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída. Requisições falhas não são cobradas.

Como testar uma chave sem cartão?

Resgate o crédito de teste de $0,50 na página da chave de API após se cadastrar. Não precisa de cartão e é válido por 7 dias, um por pessoa.

Por que uma chave válida retorna 429 imediatamente?

Você provavelmente atingiu um limite de concorrência ou por minuto. Chaves de teste permitem 2 requisições simultâneas e 60 por minuto; chaves completas permitem 8 e 300. Verifique o código de erro, diminua a velocidade ou tente novamente após alguns segundos.

Posso testar a chave no Postman ou em um app em vez de curl?

Sim. Qualquer cliente compatível com OpenAI funciona: defina a URL base para https://api.aiapisource.com/v1, cole a chave como um token Bearer e use o modelo uncensored.

Sua chave está a um clique de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API