TOKEN BOX API

Getting started

Connect to multiple AI models through one OpenAI-compatible API. Configure your client and make your first request in minutes.

Base URL
https://tokenbox.cloud/v1
All API paths are relative to this URL. Keep your API key in a server-side environment variable, never in browser code or source control.

Authentication

Create an API key in the console and send it as a Bearer token with every request:

Authorization: Bearer YOUR_TOKENBOX_API_KEY

Store it as an environment variable:

export TOKENBOX_API_KEY="sk-your-key"

List available models

Retrieve the models available to your account. Always use the exact model ID returned by this endpoint.

GET https://tokenbox.cloud/v1/models

curl https://tokenbox.cloud/v1/models \
  -H "Authorization: Bearer $TOKENBOX_API_KEY"

Create a chat completion

The Chat Completions endpoint accepts an array of messages and returns the model response.

POST https://tokenbox.cloud/v1/chat/completions

curl https://tokenbox.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {"role": "system", "content": "You are concise and accurate."},
      {"role": "user", "content": "Introduce Token Box in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

Message roles

Field	Purpose
`system`	Sets the assistant behavior and boundaries.
`user`	Contains the user request or task.
`assistant`	Represents previous assistant messages for multi-turn context.

Streaming responses

Set stream to true to receive incremental content over SSE, which is useful for real-time chat interfaces.

curl https://tokenbox.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"model":"YOUR_MODEL_NAME","stream":true,"messages":[{"role":"user","content":"Write a short product introduction."}]}'

Process each data: event and close the connection after receiving data: [DONE].

SDK examples

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKENBOX_API_KEY",
    base_url="https://tokenbox.cloud/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

JavaScript / Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENBOX_API_KEY,
  baseURL: "https://tokenbox.cloud/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_NAME",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

Error handling

Status	Common cause	What to do
401	Invalid key or missing Bearer prefix	Check the API key and authorization header.
404	Unknown model or path	Call `/models` and verify the model ID.
429	Rate or quota limit	Retry with exponential backoff and check account usage.
5xx	Temporary gateway or upstream issue	Record the request ID and retry shortly.

For production, record the HTTP status and request ID, but never log API keys or complete private user content.

Need help? Email tokenbox88@outlook.com.