API reference

Base URL: https://api.thetoken.dev/v1. Every path below is relative to this URL. Anthropic SDKs and Claude Code take the base URL without /v1 (https://api.thetoken.dev) and add /v1/messages themselves.

Authentication: Authorization: Bearer $TOKEN_API_KEY (on /messages and /models,x-api-key works too). The full OpenAPI 3.1 document: /openapi.json.

Models

Every endpoint takes a model ID or its alias. This list comes from the model catalog.

Model	Aliases	Endpoints	Tools	Structured output	Image input
`moonshotai/kimi-k3`	`kimi-k3`	/chat/completions, /responses, /messages	yes	yes	yes
`zai-org/glm-5.3`	`glm-5.3`	/chat/completions, /responses, /messages	yes	yes	no
`zai-org/glm-5.3-flash`	`glm-5.3-flash`	/chat/completions, /responses, /messages	yes	yes	yes
`deepseek/deepseek-v4-pro`	`deepseek-v4-pro`	/chat/completions, /responses, /messages	yes	yes	no
`deepseek/deepseek-v4.1-flash`	`deepseek-v4.1-flash`	/chat/completions, /responses, /messages	yes	yes	yes
`openai/gpt-oss-120b`	`gpt-oss-120b`	/chat/completions, /responses, /messages	yes	yes	no
`openai/gpt-oss-20b`	`gpt-oss-20b`	/chat/completions, /responses, /messages	yes	yes	no
`google/gemma-4-31b-it`	`gemma-4-31b-it`	/chat/completions, /responses, /messages	yes	yes	yes
`google/gemma-4-26b-a4b-it`	`gemma-4-26b-a4b-it`	/chat/completions, /responses, /messages	yes	yes	yes
`baai/bge-m3`	`bge-m3`	/embeddings	—	—	no
`meta-llama/llama-4-maverick`	`llama-4-maverick`	/chat/completions, /responses, /messages	no	not stated	yes

POST /chat/completions

Create a chat completion. OpenAI Chat Completions. With stream: true the reply comes as server-sent events (data: {...} lines, then data: [DONE]); the last chunk before [DONE] carries usage unless stream_options.include_usage is false.

Field	Type	Required	Description
`model`	string (model)	yes	A chat model ID or alias from the catalog. Without tool calling: meta-llama/llama-4-maverick.
`messages`	array of ChatMessage	yes	The conversation so far.
`max_tokens`	integer	no	Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it.
`max_completion_tokens`	integer	no	Same as `max_tokens` (newer OpenAI name).
`stream`	boolean	no	Stream the reply as server-sent events.
`stream_options`	object	no	`include_usage`: send `usage` in the last chunk (on unless set to false).
`temperature`	number	no
`top_p`	number	no
`stop`	string \| array of string	no
`tools`	array of object	no	Function tools (`{"type": "function", "function": {...}}`). Refused with 400 by models without tool calling.
`tool_choice`	string \| object	no	`auto`, `none`, `required`, or a specific function.
`response_format`	object	no	`{"type": "json_object"}` or `{"type": "json_schema", "json_schema": {...}}` on models with structured output.
`reasoning_effort`	string	no	For example `low`, `medium` or `high`, on reasoning models that accept an effort level (see each model's page).

curl https://api.thetoken.dev/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "zai-org/glm-5.3-flash",
  "messages": [
    {
      "role": "user",
      "content": "Say hello in one short sentence."
    }
  ],
  "max_tokens": 256
}'

{
  "id": "chatcmpl-8f2c1e0b6a",
  "object": "chat.completion",
  "created": 1761379200,
  "model": "zai-org/glm-5.3-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, nice to meet you!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 9,
    "total_tokens": 23,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

Errors: 400 The request is invalid, for example tools sent to a model without tool calling.; 401 The key is missing, invalid, disabled, expired or used up.; 403 Insufficient balance or key spending limit, or the model is not allowed for this key.; 429 Per-account rate limit (requests per minute) or concurrency limit (requests in flight) reached.; 503 No provider can serve the model for this key's group right now. See errors and rate limits.

POST /responses

Create a response. OpenAI Responses API. Send input as a string or as a list of input items. Streams use the Responses event types (response.output_text.delta, ..., response.completed).

Field	Type	Required	Description
`model`	string (model)	yes	A chat model ID or alias from the catalog. Without tool calling: meta-llama/llama-4-maverick.
`input`	string \| array of object	yes
`instructions`	string	no	System instructions.
`max_output_tokens`	integer	no	Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it.
`stream`	boolean	no
`tools`	array of object	no
`text`	object	no	Output format, for example `{"format": {"type": "json_schema", ...}}`.
`reasoning`	object	no	For example `{"effort": "low"}`.

curl https://api.thetoken.dev/v1/responses \
  -H "Authorization: Bearer $TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-oss-120b",
  "input": "Name three prime numbers.",
  "max_output_tokens": 512
}'

POST /messages

Create a message (Anthropic format). Anthropic Messages API at https://api.thetoken.dev/v1/messages, for Anthropic SDKs and tools such as Claude Code. Authenticate with Authorization: Bearer or x-api-key. Errors raised by the relay come in Anthropic's format ({"type": "error", "error": {...}}); key and rate-limit errors, checked before the request is read, come in the OpenAI format.

Field	Type	Required	Description
`model`	string (model)	yes	A chat model ID or alias from the catalog. Without tool calling: meta-llama/llama-4-maverick.
`max_tokens`	integer	yes	Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it.
`messages`	array of object	yes	`{"role": "user" \| "assistant", "content": string \| blocks}`.
`system`	string \| array of object	no
`stream`	boolean	no
`tools`	array of object	no	Anthropic tools (`name`, `description`, `input_schema`). Refused with 400 by models without tool calling.
`tool_choice`	object	no
`temperature`	number	no

curl https://api.thetoken.dev/v1/messages \
  -H "Authorization: Bearer $TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "moonshotai/kimi-k3",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Explain failover in one paragraph."
    }
  ]
}'

{
  "id": "msg_01a9c3e7",
  "type": "message",
  "role": "assistant",
  "model": "moonshotai/kimi-k3",
  "content": [
    {
      "type": "text",
      "text": "Failover means that when one provider fails, the request is sent to the next one."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 21
  }
}

POST /embeddings

Create embeddings. OpenAI Embeddings. input is a string or a list of strings; each result is a list of floats.

Field	Type	Required	Description
`model`	string (model)	yes	An embedding model ID or alias from the catalog.
`input`	string \| array of string	yes	Text, or a list of texts, to embed.
`encoding_format`	string	no

curl https://api.thetoken.dev/v1/embeddings \
  -H "Authorization: Bearer $TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "baai/bge-m3",
  "input": [
    "The quick brown fox",
    "Le renard brun"
  ]
}'

{
  "object": "list",
  "model": "baai/bge-m3",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.0119,
        -0.0441,
        0.0802
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

GET /models

List models. The models your key can use (all catalog models, or the key's allow-list). The public catalog with prices and providers, without a key: https://thetoken.dev/models.json.

curl https://api.thetoken.dev/v1/models \
  -H "Authorization: Bearer $TOKEN_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "moonshotai/kimi-k3",
      "object": "model",
      "created": 1626777600
    },
    {
      "id": "baai/bge-m3",
      "object": "model",
      "created": 1626777600
    }
  ]
}

Errors: 401 The key is missing, invalid, disabled, expired or used up. See errors and rate limits.