Primeiros passos

Quickstart

Faça sua primeira requisição à API do TokenLab usando cURL, Python, JavaScript, Go ou PHP. Configure sua chave de API, defina o endpoint e verifique uma resposta de Chat Completions.

Obtenha uma chave de API

Crie uma conta

Inscreva-se em tokenlab.sh usando seu e-mail, conta Google ou GitHub.

Crie e salve uma chave de API

Abra API Keys em seu workspace. Crie uma chave e salve o valor completo imediatamente; ele é exibido apenas uma vez. Se você já salvou uma chave completa, use esse valor. O prefixo exibido ou copiado da lista não pode autenticar requisições.

Verifique o saldo do workspace

Verifique seu saldo em Billing. Uma conta nova pode receber um crédito de teste único; caso contrário, ela começa com $0 e precisa de uma recarga (mínimo de $5) antes da primeira requisição. A requisição é cobrada pelo preço atual do modelo selecionado.

Mantenha a chave de API em segredo. Não a coloque em código do lado do cliente (client-side) ou em um repositório público.

Defina a chave para este terminal

Os comandos abaixo mantêm a chave fora do próprio comando. Eles a definem apenas para o terminal atual e seus processos filhos. Use um gerenciador de segredos para aplicações implantadas.

printf 'TokenLab API key: '
read -r -s TOKENLAB_API_KEY
printf '\n'
export TOKENLAB_API_KEY

Instale um cliente

pip install openai

Envie sua primeira requisição

Para a maioria das novas integrações, comece com Chat Completions em POST /v1/chat/completions.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","messages":[{"role":"user","content":"Reply only with OK."}]}'

Salve um exemplo de SDK como quickstart.py, quickstart.mjs, main.go ou quickstart.php, então execute python quickstart.py, node quickstart.mjs, go run . ou php quickstart.php. Python, JavaScript e Go usam SDKs oficiais da OpenAI; PHP usa o cliente OpenAI PHP mantido pela comunidade (PHP 8.2+).

Use POST /v1/responses apenas quando precisar de comportamento específico para Responses. O suporte para campos exclusivos de Responses depende do modelo selecionado.

Confirme o resultado

Uma requisição bem-sucedida retorna uma resposta não vazia. Abra Runs no mesmo workspace para verificar o modelo, status e uso. Para erros, siga troubleshooting. Alterar o modelo ou adicionar streaming é um próximo passo separado no guia de SDK.

Por que minha primeira chamada retorna 402?

Se a sua primeira chamada funcionará ou não depende do saldo exibido em Billing. Enquanto a oferta de crédito de teste estiver ativa, uma nova conta elegível recebe $0.25 uma única vez, para até 10 chamadas dentro de 7 dias; a 11.ª chamada retorna 402 e informa que as chamadas do teste gratuito foram esgotadas, mesmo que ainda reste um pouco de crédito. Uma conta com saldo $0 recebe HTTP 402 com o código de erro insufficient_balance. Recarregue pelo menos $5 em Billing; $5 é o valor mínimo de recarga. Em seguida, envie a mesma requisição novamente. Você não precisa de uma nova chave de API: a chave que você criou continuará funcionando assim que o saldo cobrir a requisição.

Uma primeira chamada de teste custa muito pouco. Um exemplo de requisição para deepseek-v4.1-flash custa bem menos de $0.01.

Se você já possui algum saldo, a mensagem 402 informa aproximadamente quanto a requisição precisa e qual é o seu saldo. O TokenLab retém o custo do max_tokens total antes do início da chamada, portanto, uma entrada longa ou um max_tokens grande pode precisar de mais do que um saldo pequeno. Em /v1/chat/completions e /v1/messages, quando um max_tokens menor for suficiente, a mensagem também fornece o valor para o qual reduzi-lo. Quando a entrada sozinha custa mais do que o seu saldo, a mensagem instrui a encurtar a entrada.

Uma chave que atinge seu próprio limite de gastos também retorna 402, com o código quota_exceeded. Aumente ou remova o limite em API Keys. Para lidar com 402 no código, veja error handling.

Continue construindo

Nesta página