API reference
OpenAI-compatible. One key, one base URL, every model. Requests are forwarded as-is, so any parameter your SDK sends reaches the model.
Base URL
https://toolgram.app/api/v1
Authentication
Send your key in the Authorization header as a Bearer token. Keys start with tg_live_, are stored hashed, and can be revoked from the dashboard at any time.
Authorization: Bearer tg_live_YOUR_KEY
Requests without a valid key return 401. A revoked key stops working immediately.
Endpoints
| Method | Path | Body |
|---|---|---|
| POST | /chat/completions | OpenAI chat format. Messages, tools, streaming. |
| POST | /completions | Legacy prompt format. |
| POST | /embeddings | Model id plus input text. |
| GET | /models | No body. Returns the catalog for your key. |
Other OpenAI-style paths are forwarded to the upstream provider. If a model supports a feature, the feature passes through.
Streaming
Add "stream": true and read server-sent events. Usage is still metered from the final chunk.
curl https://toolgram.app/api/v1/chat/completions \
-H "Authorization: Bearer tg_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai-gpt-oss-20b",
"messages": [{"role": "user", "content": "Count to five."}],
"max_tokens": 100,
"stream": true
}'Set max_tokens
Before a request starts we check that your balance covers the worst case. If you omitmax_tokens, we assume 2000 output tokens for that check. Set it explicitly to keep the check tight and avoid a 402 on a small balance.
Rate limits
Each key allows 120 requests per minute. Above that you get a 429 with aRetry-After header. Retry after that many seconds, with jitter.
Errors
| Status | Code | What to do |
|---|---|---|
| 401 | invalid_api_key | Key missing, mistyped or revoked. Create a new one. |
| 402 | insufficient_quota | Balance too low for this request. Top up or lower max_tokens. |
| 429 | rate_limit_error | Over 120 requests per minute. Wait for Retry-After. |
| 503 | service_disabled | The API is paused for maintenance. Check status. |
Error bodies follow the OpenAI shape:
{
"error": {
"message": "Insufficient balance. Top up your Toolgram wallet to continue using the API.",
"type": "insufficient_quota",
"code": "insufficient_quota"
}
}Billing per request
Every completed request is charged from your prepaid balance using the token counts the provider reports. Prices are per 1 million tokens, shown on Models and prices. A request that fails before reaching the model is not charged.
Post in the group with the key prefix, model id, error code and time.