Documentation

Everything you need to integrate Tokenso into your application.

Introduction

Tokenso is an OpenAI-compatible API gateway.

Because the surface is identical to OpenAI's, migration consists of replacing one value:

python — diff

import os
from openai import OpenAI

# before
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.openai.com/v1",
)

# after — nothing else changes
client = OpenAI(
    api_key=os.environ["TOKENSO_API_KEY"],
    base_url="https://api.tokenso.top/v1",
)

Nothing else changes.

Compatibility scope: chat completions, streaming, tool calling, JSON mode, vision and embeddings are supported.

Quickstart

1. Generate an API key in the console.

2. Install the OpenAI SDK.

bash

pip install openai

3. Send a request.

python — first_call.py

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENSO_API_KEY"],
    base_url="https://api.tokenso.top/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(resp.choices[0].message.content)

Authentication

Authenticate every request with a Bearer token.

bash

curl https://api.tokenso.top/v1/models \
  -H "Authorization: Bearer $TOKENSO_API_KEY"

Keys can be scoped, capped and revoked.

Never expose keys client-side. Requests carrying a secret key must originate from a trusted backend.

Base URL & routing

All requests go to a single host.

Routing behaviour:

The nearest healthy edge node terminates TLS.
The model identifier is mapped to a provider and region.
Failures retry on a secondary upstream.
Streaming responses are piped back without buffering.

Custom domains: the canonical endpoint is https://api.tokenso.top/v1.

Chat completions

The primary endpoint.

bash — POST /v1/chat/completions

curl https://api.tokenso.top/v1/chat/completions \
  -H "Authorization: Bearer $TOKENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "What is a token?"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

Request body

Field	Type	Description
modelrequired	string	Model identifier.
messagesrequired	array	Array of message objects.
temperatureoptional	number	Sampling temperature, 0–2.
max_tokensoptional	integer	Upper bound on generated tokens.
streamoptional	boolean	When true, tokens stream over SSE.
toolsoptional	array	Function definitions for tool calling.

Response

json — 200 OK

{
  "id": "chatcmpl-9xK2mQ7fLp",
  "object": "chat.completion",
  "created": 1762387200,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A token is the smallest unit of text a model processes."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 118,
    "total_tokens": 142
  }
}

Returns a standard completion object.

Streaming

Set stream: true to receive server-sent events.

python — stream.py

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a haiku about latency."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Deltas may be split mid-token.

List models

Returns every model identifier available to your key.

bash — GET /v1/models

curl https://api.tokenso.top/v1/models \
  -H "Authorization: Bearer $TOKENSO_API_KEY"

json — 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "openai",
      "context_window": 128000
    },
    {
      "id": "claude-sonnet-4",
      "object": "model",
      "owned_by": "anthropic",
      "context_window": 200000
    }
  ]
}

SDK examples

Every official OpenAI SDK works.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENSO_API_KEY"],
    base_url="https://api.tokenso.top/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Summarise the CAP theorem in 2 lines."},
    ],
)

print(resp.choices[0].message.content)

javascript — esm

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENSO_API_KEY,
  baseURL: "https://api.tokenso.top/v1",
});

const resp = await client.chat.completions.create({
  model: "gemini-2.5-flash",
  messages: [{ role: "user", content: "Summarise the CAP theorem." }],
});

console.log(resp.choices[0].message.content);

bash

curl https://api.tokenso.top/v1/chat/completions \
  -H "Authorization: Bearer $TOKENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Summarise the CAP theorem."}]
  }'

Errors & rate limits

Error responses mirror OpenAI's schema.

Status	Type	Meaning
400	invalid_request_error	Malformed request body.
401	authentication_error	Missing or revoked key.
402	insufficient_quota	Insufficient balance.
404	model_not_found	Unknown model identifier.
429	rate_limit_exceeded	Rate limit exceeded.
503	upstream_unavailable	All upstreams failed.

Retry policy: retry 429 and 503 with exponential backoff.

FAQ

Yes for chat completions.

Only with a restricted key.

Caching is applied at the upstream level.

Replace the base URL and API key.