Documentation sections
Send the first routed request.
Create and activate a Tokaroo key, keep it in a server-side secret store, and call the OpenAI-compatible endpoint with auto.
curl https://api.tokaroo.com/v1/chat/completions \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Explain this error in plain language"}
]
}'max, pro, auto, fast, and basic. Start with auto unless you have a specific cost, latency, or quality objective.Use one Tokaroo key from a trusted runtime.
OpenAI-compatible and native REST calls accept Authorization: Bearer tok_.... Anthropic clients may send the same key in x-api-key. Gemini clients may use x-goog-api-key.
Load the key from an environment variable or secret manager.
Pass the key using the harness's provider credential setting.
Call your own backend or use a short-lived scoped credential. Never ship a permanent key in a public bundle.
Request the outcome Tokaroo should optimize.
The hardest and highest-stakes work where capability is the first requirement. Uses the measured frontier band and selects efficiently inside that elite group.
Serious daily technical, business, production, and customer-facing work. Chooses economically inside a substantially stronger measured quality band.
The default for applications that want Tokaroo to make the whole routing decision. Balances quality, cost, speed, reliability, tools, context, and escalation risk.
Rapid answers, edits, extraction, and interactive back-and-forth. Keeps an acceptable task-specific quality bar, then prioritizes measured speed.
Everyday questions and routine tasks where you need an answer, not a project. Selects the cheapest route that is working and appropriate for lightweight work.
The percentages are fallback quality ratios relative to the best freshly measured candidate for the task family. They are not statistical percentiles. Fresh task-specific quality clusters can supersede a fixed fallback floor when evidence coverage is sufficient.
Quality is measured separately for reasoning, code, math, reading, writing, tools, multilingual, and spatial work.
The best fresh measured output in that task family becomes the 100% quality ceiling.
Only compatible candidates clearing the requested mode's quality checks enter its decision basket.
Tokaroo then weighs speed, price, reliability, context, tools, and availability inside that basket.
General chat and reasoning
Awaiting fresh evidence | Conservative fallback floors
Code and tool work
Awaiting fresh evidence | Conservative fallback floors
Math and quantitative reasoning
Awaiting fresh evidence | Conservative fallback floors
Reading and synthesis
Awaiting fresh evidence | Conservative fallback floors
Writing and editing
Awaiting fresh evidence | Conservative fallback floors
Structured data and tool decisions
Awaiting fresh evidence | Conservative fallback floors
Multilingual work
Awaiting fresh evidence | Conservative fallback floors
Spatial reasoning
Awaiting fresh evidence | Conservative fallback floors
Evaluation evidence is limited to successful Tokaroo tests in the latest 30-day window; imported zero-sample signals are excluded. Basket membership, the concrete serving model, the serving provider, and private settlement cost remain internal.
/v1/models/v1/pricing/v1/catalogChange the base URL, key, and model.
Existing OpenAI clients can use Tokaroo at https://api.tokaroo.com/v1. Chat Completions supports standard messages, tools, structured output fields, and streaming where the selected route is compatible.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKAROO_API_KEY"],
base_url="https://api.tokaroo.com/v1",
)
response = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "Review this function"}],
)
print(response.choices[0].message.content)/v1/chat/completions/v1/modelsPreserve Responses-native tool loops.
Use the Responses surface for clients such as Codex that rely on its native input, output, tool, and streaming event shapes.
curl https://api.tokaroo.com/v1/responses \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "pro",
"input": "Plan a safe database migration"
}'/v1/responsesUse Messages without changing its tool protocol.
The Anthropic-compatible surface accepts Messages requests, system content, tools, tool choice, streaming, and token counting. Set the base URL to https://api.tokaroo.com.
curl https://api.tokaroo.com/v1/messages \
-H "x-api-key: $TOKAROO_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "auto",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Summarize the incident"}
]
}'/v1/messages/v1/messages/count_tokensUse native GenerateContent routes.
Gemini clients can call GenerateContent, streamGenerateContent, countTokens, and the model list with a Tokaroo model ID in the path.
curl "https://api.tokaroo.com/v1beta/models/auto:generateContent" \
-H "x-goog-api-key: $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{"text": "Draft a release note"}]
}]
}'/v1beta/models/{model}:generateContent/v1beta/models/{model}:streamGenerateContent/v1beta/models/{model}:countTokensKeep the native wire for tool-heavy clients.
Set stream: true for server-sent events on compatible text routes. Keep tool definitions and tool results in the protocol the client already uses; Tokaroo evaluates model compatibility before scoring a route.
curl -N https://api.tokaroo.com/v1/chat/completions \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fast",
"stream": true,
"messages": [{"role": "user", "content": "Give me three names"}]
}'Log the Tokaroo request without exposing the internal route.
Successful responses provide customer-safe usage fields. Concrete model selection, serving provider, upstream prices, internal margin, and failed candidate diagnostics remain private.
| Header | Meaning |
|---|---|
x-tokaroo-trace-id | An opaque identifier for support and usage correlation. |
x-tokaroo-requested-model | The requested Tokaroo mode. |
x-tokaroo-cost | The customer charge in USD. |
x-tokaroo-input-tokens | Recorded input tokens. |
x-tokaroo-output-tokens | Recorded output tokens. |
x-tokaroo-latency-ms | End-to-end runtime latency. |
x-tokaroo-cache | Cache status when that wire supports it. |
Agent systems may also send x-tokaroo-harness-ref with a supported profile ID so Tokaroo can apply tested harness compatibility preferences.
Retry only failures that can recover.
400Fix the request shape, unsupported field, or incompatible model requirement before retrying.
401Provide a valid Tokaroo key in the expected authentication header.
402Add credits or resolve the account's spend access before retrying.
429Respect retry-after, use exponential backoff, and add jitter.
503No compatible route is currently available. Respect retry-after and retry from a queue where possible.
Import the public contract.
The public specification covers Tokaroo's five model IDs, four compatible text formats, multimodal endpoints, customer-safe usage, and prepaid balance. It intentionally excludes private route selection and upstream commercial data.
Route more than text through the same account.
Tokaroo exposes compatible endpoints for embeddings, images, speech, transcription, video, realtime audio, and avatar workflows. Raspy supplies speech, transcription, realtime audio, and avatar capabilities; images and video use the broader compatible model network.
/v1/embeddings/v1/images/generations/v1/audio/speech/v1/audio/transcriptions/v1/videos/v1/realtime/transcriptions/v1/realtime/speech/v1/realtime/avatar/v1/avatars/v1/avatar/rendersConfigure the harness. Keep execution where it belongs.
Tokaroo publishes profiles for Codex, Claude Code, Hermes, OpenClaw, Kimi Code, DeepSeek Harness, Qwen Code, Gemini CLI, Grok Build, Goose, and OpenCode. The harness owns tools, files, and execution; Tokaroo owns the model route.
Open the integration directory