Getting started

API Basics

Rules that apply to every TokenRa request: where to send it, how to authenticate, and how to handle errors.

BASE URL

Base URL

Use	Base URL	Clients
OpenAI-compatible: chat, responses, images, video	`https://tokenra.io/v1`	OpenAI SDKs, LangChain, most tools
Anthropic Messages	`https://tokenra.io`	Anthropic SDKs, Claude Code (they append `/v1/messages`)
Models available to your key	`GET https://tokenra.io/v1/models`	Any HTTP client

AUTH

Authentication

Method	Header or parameter	Where it works
Bearer token (recommended)	`Authorization: Bearer sk-...`	Every endpoint
x-api-key	`x-api-key: sk-...`	`/v1/messages` and `/v1/models` (Anthropic format)
Google style	`x-goog-api-key` header or `?key=` query	Gemini-native paths under `/v1beta/models`

Keep keys server-side

Never put a key in browser or mobile code. If a key leaks, delete it in the console and create a new one.

CONVENTIONS

Request conventions

Send JSON in UTF-8 with Content-Type: application/json. Image edits use multipart/form-data.
Streaming responses are server-sent events: data: lines ending with data: [DONE].
Reasoning models and image generation can take tens of seconds. Use a client timeout of at least 120 seconds, or stream.

ASYNC

Async tasks (video)

Video endpoints return a task_id right away. Query GET /v1/video/generations/{task_id} every 10–15 seconds until the status is final.

data.status	Meaning
`NOT_START` / `SUBMITTED` / `QUEUED`	Accepted, waiting to start.
`IN_PROGRESS`	Generating.
`SUCCESS`	Done. Download `result_url`.
`FAILURE`	Failed. The reason is in `fail_reason`; the pre-charged amount is refunded.

ERRORS

Errors

Errors come back as an error object. The message ends with a request id; include it when you contact support.

{
  "error": {
    "message": "Invalid token (request id: 202610231454005716007698268d9d6k7qSUTYb)",
    "type": "new_api_error",
    "code": ""
  }
}

HTTP	error.code	Meaning	What to do
`401`	—	Missing, wrong or deleted API key. The message is `Invalid token`.	Check the `Authorization: Bearer` header and the key in the console.
`400`	—	The body is not valid JSON.	Fix the JSON and send `Content-Type: application/json`.
`500`	`invalid_request`	A required field is missing, for example `messages`.	Add the field named in the message. Retrying will not help.
`403`	`insufficient_user_quota`	Your balance or plan quota is used up.	Top up in the console, then retry.
`503`	`model_not_found`	Unknown model ID, or no channel serves it for your group.	Check the ID in the model list or with `GET /v1/models`.
`429`	—	Too many requests.	Back off exponentially and retry.
`5xx`	—	The upstream provider failed or timed out.	Retry a few times; keep the request id if it persists.

RETRIES

Rate limits & retries

Retry 429 and 5xx with exponential backoff (for example 1 s, 2 s, 4 s) and stop after a few attempts.
Do not retry 400, 401, 403 or model_not_found; fix the request first.
Too many parallel requests from one IP can be answered with HTTP 503 and an HTML page instead of JSON. Lower the concurrency, back off and retry, and do not assume every error body is JSON.

BILLING

Usage & billing

Text models report usage with prompt, completion, cached and reasoning tokens. Image models bill per request; video models bill per task.
Failed requests refund the pre-charged amount. The usage log in the console is the final record.
Live rates for every model are in the Model Square.