Tokenator API documentation

Base URLs and authentication

Tokenator has two entry points. One speaks the OpenAI dialect, the other the Anthropic dialect. Pick whichever your client already understands; the proxy handles conversion between the formats.

The key is also accepted as Authorization: Bearer on the Anthropic entry point, which makes life easier for clients that support only one auth style.

Endpoints

Your first request

curl https://api.tokenator.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-tokenator-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

curl https://api.tokenator.top/anthropic/v1/messages \
  -H "x-api-key: sk-your-tokenator-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Streaming

Add "stream": true and the answer arrives as server-sent events. For long answers this is more than a convenience: without streaming the client waits for the whole response and may drop on its own timeout.

When a response takes a while to form, Tokenator sends keep-alives so intermediate proxies do not close the connection.

How input and output tokens are counted

Input is everything sent to the model: the system prompt, message history, tool definitions, attached files. Output is everything the model generated, including reasoning tokens even when you never see them in the response.

The key limit is charged (input + output) × the model multiplier. Each model has its own multiplier, shown on its catalog page. Raw upstream tokens appear in the key's stats; billing applies the coefficient.

The practical consequence: a long conversation history is input that gets paid for again on every request. In agent workflows it is usually the bulk of the spend, not the model's answers.

What a context window is

The context window is the ceiling on how many tokens a model can hold at once — input and output together. Exceed it and the upstream returns an error rather than silently truncating your prompt.

Max output is a separate limit: how many tokens the model may produce in a single answer. For most models it is far smaller than the context. Both values are listed per model in the catalog.

Tools and function calling

Tools are declared the usual way for your format: a tools array in the OpenAI request or in the Anthropic request. The model does not call functions itself — it returns an intent to call, your code runs the function and sends the result as the next message.

Tokenator converts tool definitions between formats, so the same tool set works on both entry points. Client-side server tools for web search and web fetch are stripped from the request: they would be executed by the upstream rather than your code, making behaviour unpredictable.

Repeated tool definitions and duplicated content blocks in the history are collapsed before sending — this shrinks input without changing the meaning of the request.

How to enable reasoning

The reasoning_effort field is forwarded upstream unchanged. Models that do not understand it ignore the field — no error is raised.

Separately, the key itself has a reasoning switch in your account that applies regardless of what the client sends. With reasoning off for the key, extended thinking is not used.

Budget note: reasoning tokens are billed as output. A high effort level can multiply spend several times over for the same visible answer.

Files and images in the input

Images are passed the standard way for your format — as part of the message content. The model must support image input; the catalog lists this as a separate field.

Text attachments (.md, .txt) and PDFs with a text layer are handled by the proxy itself: the text is extracted and inserted as a text part. Scans and files without a text layer are forwarded to the model as a file.

Errors and limits

Upstream provider errors are not passed through: instead of third-party texts and service names you get a generic message. When several providers serve a model, Tokenator tries the next one by priority first and only returns an error once all of them are exhausted.

Response limit (output limit)

On top of the overall token volume, every key has a separate response limit: the maximum total number of tokens the key may produce in model answers. It is a percentage of the whole bundle — initial volume plus every top-up — and only output tokens count against it; input tokens do not.

The current default for new keys is 6%. The exact percentage for a given key is shown in your account, and the terms are fixed in the terms of service, which take precedence over any text on the site.

Key lifetime

A bundle stays valid until its token limit is exhausted or its key lifetime expires — whichever comes first. Under the current terms of service, a key issued with a bundle lives for 3 months (90 calendar days) from issuance, after which it is deactivated and unused tokens are not refunded.

Size your bundle against your real burn rate: in agent workflows a long conversation history consumes input tokens faster than expected. The remaining balance and the issue date are always visible in your account.

Usage restriction on Claude models

How to check an API key

The fastest way is to ask the service what this key can access. The request costs nothing.

curl https://api.tokenator.top/v1/models \
  -H "Authorization: Bearer sk-your-tokenator-key"

curl https://api.tokenator.top/v1/tokens \
  -H "Authorization: Bearer sk-your-tokenator-key"

An empty or filtered model list means the key is valid but the models are not allowed for it. A 401 means the key itself is invalid.

FAQ

Read next