Getting Started
Quickstart
Make your first TokenLab API request with cURL, Python, JavaScript, Go, or PHP. Set up your API key, configure the endpoint, and verify a Chat Completions response.
Get an API key
Create an account
Sign up at tokenlab.sh using your email, Google, or GitHub account.
Create and save an API key
Open API Keys in your workspace. Create a key and save the full value immediately; it is shown only once. If you already saved a full key, use that value. The prefix shown or copied from the list cannot authenticate requests.
Check the workspace balance
Check your balance in Billing. A new account may get a one-time trial credit; otherwise it starts at $0 and needs a top-up (minimum $5) before the first request. The request is billed at the selected model’s current price.
Keep the API key secret. Do not put it in client-side code or a public repository.
Set the key for this terminal
The commands below keep the key out of the command itself. They set it only for the current terminal and its child processes. Use a secret manager for deployed applications.
printf 'TokenLab API key: '
read -r -s TOKENLAB_API_KEY
printf '\n'
export TOKENLAB_API_KEYInstall a client
pip install openaiSend your first request
For most new integrations, start with Chat Completions on 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."}]}'Save one SDK example as quickstart.py, quickstart.mjs, main.go, or quickstart.php, then run python quickstart.py, node quickstart.mjs, go run ., or php quickstart.php. Python, JavaScript, and Go use official OpenAI SDKs; PHP uses the community-maintained OpenAI PHP client (PHP 8.2+).
Use POST /v1/responses only when you need Responses-specific behavior. Support for Responses-only fields depends on the selected model.
Confirm the result
A successful request returns a non-empty answer. Open Runs in the same workspace to check its model, status, and usage. For errors, follow troubleshooting. Changing the model or adding streaming is a separate next step in the SDK guide.
Why does my first call return 402?
Whether your first call works depends on the balance shown in Billing. While the trial-credit offer runs, an eligible new account gets $0.25 once, for up to 10 calls within 7 days; the 11th call returns 402 and says the free trial calls are used up, even if a little credit is left. An account with a $0 balance gets HTTP 402 with the error code insufficient_balance. Top up at least $5 in Billing; $5 is the minimum top-up. Then send the same request again. You do not need a new API key: the key you created keeps working once the balance covers the request.
A first test call costs very little. One example request to deepseek-v4.1-flash costs far below $0.01.
If you already have some balance, the 402 message says about how much the request needs and what your balance is. TokenLab holds the cost of the full max_tokens before the call starts, so a long input or a large max_tokens can need more than a small balance. On /v1/chat/completions and /v1/messages, when a smaller max_tokens would fit, the message also gives the value to lower it to. When the input alone costs more than your balance, it says to shorten the input instead.
A key that reaches its own spending limit also returns 402, with the code quota_exceeded. Raise or remove the limit under API Keys. To handle 402 in code, see error handling.