Tokonomix Gateway — Raw HTTP / OpenAI SDK

This guide shows how to call the Tokonomix gateway directly from scripts, CI pipelines, or any HTTP client — without a coding-agent IDE.

Base URLs

All requests require Authorization: Bearer tok_live_....

Authentication

export TOKONOMIX_API_KEY="tok_live_..."

Every request:

Authorization: Bearer $TOKONOMIX_API_KEY

Chat completions

Single-model (passthrough)

curl https://tokonomix.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Explain JWT in one paragraph."}]
  }'

Consensus (multi-model council)

Add "mode": "consensus" to the request body. The gateway picks a default council (3–5 models from different families) and returns a synthesised answer.

curl https://tokonomix.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "mode": "consensus",
    "messages": [{"role": "user", "content": "Review this SQL for injection risks: SELECT * FROM users WHERE id = '"'"'" + userId + '"'"'"}]
  }'

Optional consensus parameters:

Embeddings

curl https://tokonomix.ai/api/v1/embeddings \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox"
  }'

Response:

{
  "object": "list",
  "data": [{"object": "embedding", "index": 0, "embedding": [0.021, ...]}],
  "usage": {"prompt_tokens": 5, "total_tokens": 5}
}

Use /api/v1/models (authenticated) to discover available embedding model slugs.

Image generation

curl https://tokonomix.ai/api/v1/images/generations \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A photorealistic mountain at sunrise",
    "n": 1,
    "size": "1024x1024"
  }'

Response: data[0].b64_json — base64-encoded PNG.

Image editing

For OpenAI-compatible models (multipart/form-data):

curl https://tokonomix.ai/api/v1/images/edits \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -F model="dall-e-2" \
  -F prompt="Add a red balloon" \
  -F image="@photo.png"

Do NOT set Content-Type: multipart/form-data manually when using curl -F. curl sets it automatically with the correct boundary. Setting it manually causes a 400.

For Gemini models (JSON body with base64):

curl https://tokonomix.ai/api/v1/images/generations \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash-exp",
    "prompt": "Add a red balloon",
    "image": "<base64-encoded-PNG>",
    "image_mime_type": "image/png"
  }'

Check /api/v1/image-capabilities (no auth) for the full model matrix.

Audio transcription

curl https://tokonomix.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -F model="whisper-1" \
  -F file="@recording.mp3"

Response: { "text": "..." }

Model catalog

curl https://tokonomix.ai/api/v1/models \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY"

Filter by capability (query param output_modality):

# Embedding models only
curl "https://tokonomix.ai/api/v1/models?output_modality=embedding" \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY"

Per-call introspection

After a call, retrieve cost and latency by request ID:

curl "https://tokonomix.ai/api/v1/generation?id=<request_id>" \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY"

Anthropic-Messages endpoint

For agents that use the Anthropic SDK directly (not OpenAI-compatible):

curl https://tokonomix.ai/api/anthropic/v1/messages \
  -H "Authorization: Bearer $TOKONOMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

This endpoint supports Anthropic-style tool calls, cache_control breakpoints, and streaming. Single-model only — consensus is available on the OpenAI-compatible endpoint only.

OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://tokonomix.ai/api/v1",
    api_key="tok_live_...",
)

# Chat
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Summarise this code: ..."}],
)
print(resp.choices[0].message.content)

# Embeddings
emb = client.embeddings.create(model="text-embedding-3-small", input="Hello world")
print(emb.data[0].embedding[:5])

# Image generation
img = client.images.generate(model="gpt-image-2", prompt="A sunset", n=1, size="512x512")
# img.data[0].b64_json contains the PNG

# Audio
with open("speech.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(model="whisper-1", file=f)
print(transcript.text)

OpenAI SDK (TypeScript / Node)

import OpenAI from "openai";
import fs from "fs";

const toko = new OpenAI({
  baseURL: "https://tokonomix.ai/api/v1",
  apiKey: process.env.TOKONOMIX_API_KEY ?? "",
});

// Chat
const chat = await toko.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Review this migration for data-loss risks." }],
});
console.log(chat.choices[0].message.content);

// Embeddings
const emb = await toko.embeddings.create({
  model: "text-embedding-3-small",
  input: "semantic search query",
});
console.log(emb.data[0].embedding.slice(0, 5));

// Audio
const transcript = await toko.audio.transcriptions.create({
  model: "whisper-1",
  file: fs.createReadStream("recording.mp3"),
});
console.log(transcript.text);

MCP via npx (any terminal)

You can also start the MCP server in stdio mode and call it from any MCP-compatible client:

TOKONOMIX_API_KEY=tok_live_... npx tokonomix-mcp

Or install globally for faster startup:

npm install -g tokonomix-council-mcp
TOKONOMIX_API_KEY=tok_live_... tokonomix-mcp

Latest version: 1.6.2

GitHub: https://github.com/TokonoMix/tokonomix-council-mcp

Error reference