TokenSmith API · Reference

OpenAI-compatible API

The gateway exposes OpenAI-compatible POST /v1/chat/completions, POST /v1/images/generations (supported image models only), and GET /v1/models (list and retrieve catalog entries). Client libraries that accept a custom baseURL, including the official OpenAI SDKs, can point at TokenSmith’s host instead of api.openai.com.

Protocol: HTTPS, JSON request and response bodies
Auth: Authorization: Bearer <api_key> (same header shape as OpenAI)
Version prefix: /v1/... on supported routes

Base URL & authentication

Configure your client’s base URL to TokenSmith’s production API endpoint: https://api.tokensmith.us/v1.

Current OpenAI-compatible base URL

https://api.tokensmith.us/v1

Create and rotate keys in API keys. Treat keys like production secrets; the example key below is fabricated.

Example Authorization header

Authorization: Bearer tokensmith_live_0000000000000000000000000000000000000000000000000000000000000000

Chat completions

Endpoint: POST /v1/chat/completions. TokenSmith forwards an OpenAI-style chat completions payload (messages, model, tools, tool_choice, etc.) to the routed upstream provider. For now, send "stream": false.

Auth: Authorization: Bearer <tokensmith_live_…> or X-API-Key: <tokensmith_live_…> for server-side API calls, or Authorization: Bearer <Supabase access token> for signed-in console sessions. All three debit the same wallet.

Example Request body (illustrative)

{
  "model": "gpt-5.6-terra",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Say hello in one sentence." }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

If model is omitted, the gateway currently defaults to gpt-5.6-terra. Copyable requests in several languages are in SDK examples below. Deep dive in the console: Chat API · model identifiers on Models.

Image generations

Endpoint: POST /v1/images/generations. Same JSON shape as OpenAI (for example model, prompt, optional n). Only models listed under image generation on the Models page are accepted; the Worker forwards to Together for the current image SKUs (FLUX, GPT Image, Seedream, Nano Banana, Qwen Image, etc.) and debits wallet credits per generated image.

Example Request body

{
  "model": "black-forest-labs/FLUX.2-pro",
  "prompt": "A serene lake at sunset with mountains in the background",
  "n": 1
}

The response returns a list of generated images. Each item includes a url field pointing to the generated image, or a b64_json field with base64-encoded PNG data.

Example Response body

{
  "data": [
    {
      "url": "https://example-cdn.com/generated/image-abc123.png",
      "prompt": "A serene lake at sunset with mountains in the background"
    }
  ]
}

Download proxy: use GET /v1/images/download?url=… with an authenticated token to fetch image bytes directly (avoids browser CORS limits). See the Images API playground for a live demo.

Video generations

Endpoint: POST /v1/videos. Creates a video job. The Worker routes to upstream providers (Sora, Veo 3.1, Seedance, and supported Fal Kling regular-video endpoints) based on the selected model and debits wallet credits proportional to the requested duration in seconds.

Video generation is asynchronous: the create call returns a job identifier, and you poll GET /v1/videos/{video_id} for status updates until the job completes with a video URL.

Example Create request body

{
  "model": "sora-2",
  "prompt": "A timelapse of a flower blooming in a garden",
  "seconds": 8
}

Duration options vary by model. Sora 2 supports 4, 8, or 12 seconds. Other models support 3–30 seconds. Longer videos cost more credits.

Example Create response (job created)

{
  "id": "vg_abc123def456",
  "status": "queued",
  "model": "sora-2",
  "prompt": "A timelapse of a flower blooming in a garden",
  "seconds": 8
}

Example Poll response (completed)

{
  "id": "vg_abc123def456",
  "status": "succeeded",
  "model": "sora-2",
  "prompt": "A timelapse of a flower blooming in a garden",
  "seconds": 8,
  "url": "https://example-cdn.com/generated/video-def789.mp4"
}

Supported models include Sora 2, Veo 3.1 (various tiers), and Seedance 1.0 Lite. See the full list on the Models page or try video generation in the Video API playground.

SDK examples

These examples use the current OpenAI-compatible base URL and a TokenSmith API key. Replace the placeholder key and model as needed.

Example Chat completions

curl -sS https://api.tokensmith.us/v1/chat/completions \
  -H "Authorization: Bearer tokensmith_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","messages":[{"role":"user","content":"Hi"}],"stream":false}'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "tokensmith_live_your_api_key_here",
  baseURL: "https://api.tokensmith.us/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.6-terra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Say hello in one sentence." }
  ],
  stream: false,
});

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

from openai import OpenAI

client = OpenAI(
    api_key="tokensmith_live_your_api_key_here",
    base_url="https://api.tokensmith.us/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Say hello in one sentence."},
    ],
    stream=False,
)

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

const response = await fetch(
  "https://api.tokensmith.us/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer tokensmith_live_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-5.6-terra",
      messages: [
        { role: "user", content: "Say hello in one sentence." }
      ],
      stream: false,
    }),
  }
);

const data = await response.json();
console.log(data);

Supported routes

These are the routes implemented by the current Worker:

GET /health: unauthenticated health check
POST /v1/chat/completions: OpenAI-compatible chat completions proxy
POST /v1/images/generations: OpenAI-compatible image generation proxy (catalog-limited models)
POST /v1/videos, GET /v1/videos/{id}: video proxy to OpenAI (Sora), Google Veo, Together, or supported Fal Kling regular-video endpoints by model (create job, then poll status; catalog-limited models; wallet debit scales with seconds or duration on create)
POST /v1/{fal-model-path}/motioncontrol: Fal Kling motion control with multipart motion video and character image fields; supported paths are listed on Models.
GET /v1/images/download?url=…: authenticated proxy to fetch image bytes for saving (HTTPS URLs on an allowlisted CDN/provider host; avoids browser CORS limits). Operators can extend allowed host suffixes with Worker env IMAGE_DOWNLOAD_ALLOWED_HOST_SUFFIXES (comma-separated).
GET /v1/models, GET /v1/models/{model}: list or retrieve one model (OpenAI-shaped JSON; same auth as chat)
GET /v1/api-keys: list API keys for the signed-in Supabase user
POST /v1/api-keys: create an API key for the signed-in Supabase user
PATCH /v1/api-keys/{id}: JSON body { "disabled": true | false } to block or allow requests (revoked keys cannot be toggled)
DELETE /v1/api-keys/{id}: permanently delete an API key row by UUID
POST /v1/checkout/credits: create a Stripe Checkout session from a signed-in user and Stripe Price ID
POST /webhooks/stripe: Stripe webhook receiver

Models & routing

Model selection happens inside POST /v1/chat/completions, POST /v1/images/generations for image SKUs, or POST /v1/videos for video SKUs. GET /v1/models returns the catalog in OpenAI list format (IDs match the Models page). Each object may include TokenSmith extensions: tokensmith_supports_chat, tokensmith_chat_attachment_inputs, tokensmith_supports_image_generation, tokensmith_supports_video_generation, tokensmith_supports_motion_control, and tokensmith_motion_control_path so clients can filter controls per endpoint and selected model. Chat attachment values currently include image, pdf, and audio where the routed provider supports them. For model IDs that contain /, URL-encode the path segment when calling GET /v1/models/{model}.

claude-*: routed to Anthropic’s OpenAI-compatible API
gemini-*: routed to Google’s OpenAI-compatible API
grok-*: routed to xAI
gpt-*, o1*, o3*, o4*, chatgpt-*: routed to OpenAI
Everything else is treated as an open-weights / org/model-style id (for example deepseek-ai/DeepSeek-V4-Pro)

Models that expose tokensmith_reasoning_effort from GET /v1/models accept a provider-neutral tokensmith_reasoning_effort string on chat requests. Use one of that model’s advertised supported_values; TokenSmith validates and translates it to the routed provider.

Availability still depends on which upstream credentials are configured on the Worker and which model rates are loaded in your database.

Streaming & tools

Streaming: not available in the current gateway version. Send "stream": false and expect a standard JSON response body.

Tools / function calling: pass tools and tool_choice in the same shape as OpenAI’s chat completions. The gateway forwards those fields, but provider behavior differs, so validate the exact model you plan to ship against.

Console & account

Operational pages for keys, usage, billing, and account settings:

Credits

TokenSmith bills in credits. API usage debits credits according to each model’s rate. Balance and top-up appear on Billing; usage detail appears on Usage.

Errors & limits

Errors use HTTP status codes and JSON bodies, but the exact shape is not fully normalized yet. Some responses return OpenAI-style payloads such as { "error": { "message": "...", "type": "..." } }, while management routes may return simpler payloads such as { "error": "invalid_api_key" }.

Rate limits are not yet exposed as documented response headers.

API reference