# Tokonomix.ai

> Multi-model AI consensus — ask several frontier LLMs the same high-stakes question and have an
> independent judge reconcile one answer, with disagreements surfaced (not averaged away). A one-key,
> OpenAI- and Anthropic-compatible gateway carries it as transport and reaches 130+ models across
> families, with EU data-residency routing for prompts that contain personal data. Plus daily
> latency/quality benchmarks in six languages.

## About

<!-- capabilities:start -->
## Live gateway capabilities

> Rendered live from the same platform capability flags as `GET /api/v1/capabilities`;
> revalidated hourly. No manual sync step exists.

| Capability | Status | Endpoint |
|---|---|---|
| Chat completions (single-model) | ✅ ON | `POST /api/v1/chat/completions` |
| Consensus multi-model council | ✅ ON | `POST /api/v1/chat/completions (mode=consensus)` |
| Image generation (text→image) | ✅ ON | `POST /api/v1/images/generations` |
| Image editing (existing image) | ✅ ON | `POST /api/v1/images/edits` |
| Image input in chat (vision) | ✅ ON | `POST /api/v1/chat/completions` |
| Text embeddings | ✅ ON | `POST /api/v1/embeddings` |
| Speech-to-text transcription | ✅ ON | `POST /api/v1/audio/transcriptions` |
| Rerank | ❌ OFF | `POST /api/v1/rerank` |
| Web search plugin | ❌ OFF | `chat body: "plugins":[{"id":"web"}]` |
| Server-side tool injection | ✅ ON | `POST /api/anthropic/v1/messages` |

Machine-readable version with SDK snippets and gotchas: `GET /api/v1/capabilities`
<!-- capabilities:end -->

Tokonomix is two things behind one key:
1. A **consensus gateway** — an OpenAI-compatible (and Anthropic-Messages-compatible) API that
   routes single-model calls OR runs a cross-family **council**: 2–6 proposer models answer
   independently and blind, then an independent judge synthesises and flags disagreement. This is
   a recall amplifier for correctness, not a truth oracle — it reduces single-model error and
   surfaces blind spots; it does not guarantee correctness.
2. An **independent benchmark** — transparent, reproducible daily speed and intelligence scores for
   major models, with the full prompt set and scoring methodology published.

Tokonomix is an InterIP Networks BV initiative, sister site to ZelixAI (https://zelixai.ai).

## What it is for (positioning)

Two distinct jobs, one key — do not conflate them:

- **Consensus = a verification / agent-QA layer.** Cross-check a high-stakes answer across several
  frontier models before it ships: code review, security review, fact-checking, legal/compliance
  statements, anything irreversible. The independent judge surfaces the disagreement a single model
  hides. Copyable honest framing: **"a recall amplifier, not a truth oracle — it reduces
  single-model error and surfaces blind spots, it does not guarantee correctness."**
- **Agents Never Sleep (ANS) = unattended run-to-completion.** A separate, open skill/harness that
  drives a backlog overnight without stalling on questions, with durable per-ticket state and
  reversibility — and can call a consensus council as its advisory review gate. ANS owns the
  "unattended / overnight / backlog" keywords; consensus owns the "verify / review / cross-check"
  keywords. (The ANS write-up is internal-only for now.)

The MCP server `tokonomix-council-mcp` (npx) exposes the consensus tools to coding agents
(Claude Code, Cursor, Cline, Continue, Zed). Registry metadata: /.well-known/mcp/server.json.

## Agent integration — SDK choice and gotchas

**Use the OpenAI SDK (or any OpenAI-compatible HTTP client) for ALL Tokonomix endpoints** —
chat completions, image generation, embeddings, and audio transcription all live under the same
`https://tokonomix.ai/api/v1` base URL with the same Bearer token. There is NO need for
provider-specific SDKs (FAL, Replicate, etc.) or custom plugins.

```python
# Python — one client for everything
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=[...])

# Image generation — same client, same base_url
img = client.images.generate(model="gpt-image-2", prompt="...", n=1, size="1024x1024")

# Embeddings — same client
emb = client.embeddings.create(model="text-embedding-3-small", input="...")

# Audio transcription — same client
with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(model="whisper-1", file=f)
```

```typescript
// TypeScript — same pattern
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://tokonomix.ai/api/v1", apiKey: "tok_live_..." });
```

**Common mistakes to avoid:**

- **Do NOT use `fal_client`, Replicate SDK, or other image-generation SDKs.** The OpenAI SDK's
  `images.generate()` call works natively via Tokonomix's `/api/v1/images/generations` endpoint.
- **Do NOT hardcode model slugs.** Fetch `/api/v1/models` (authenticated) to discover available
  models; the catalog updates as new providers are added.
- **Do NOT set a separate `OPENAI_API_KEY` env var.** Use a single Tokonomix key for all calls.
  The gateway routes to the appropriate upstream provider transparently.
- **For consensus/cross-model verification**, use the `tokonomix_consensus_ask` MCP tool or POST
  to `/api/v1/chat/completions` with `"mode": "consensus"` in the request body.
- **Do NOT set `Content-Type: multipart/form-data` manually** when calling `/api/v1/images/edits`.
  Let your HTTP client set it automatically so the boundary parameter is included.
- **Image generation ≠ image editing.** They are separate capabilities, separate endpoints, and
  separate prices. Fetch `/api/v1/image-capabilities` (no auth) to see which models support which.
- **Embeddings use the same base URL** — no separate endpoint prefix needed. The gateway routes
  to the appropriate embedding provider based on the model slug.

Full integration reference: `GET /api/v1/capabilities` (authenticated) returns a structured
machine-readable integration guide including endpoint list, SDK snippet, and current gotchas.
Public image guide (no auth): `GET /api/v1/image-capabilities`.

## Capabilities (live)

These are available today through the API and the MCP server:

- **Consensus modes** — `consensus` (one merged answer), `diff` (agreements + disagreements, keeps
  the lone dissent), `best_of` (judge picks the strongest), `raw` (all answers, no judge).
- **Single-model passthrough** — a cheap, plain call to any one model (no council) when you don't
  need verification.
- **Tool calling** — OpenAI-style function/tool calls on single-model passthrough (non-streaming).
- **Vision / image-input consensus** — send an image; multiple vision models judge it and a judge
  synthesises with blind-spot notes.
- **Image generation** — create new images from text prompts. `POST /api/v1/images/generations`
  (JSON body). Models: gpt-image-2, gpt-image-1.5, Gemini image variants.
- **Image editing** — modify existing photos with a prompt (inpainting, additions, style).
  `POST /api/v1/images/edits` (multipart/form-data for OpenAI models) or
  `POST /api/v1/images/generations` with an `image` base64 field (for Gemini models).
  These are **distinct capabilities** with their own pricing — check `/api/v1/image-capabilities`.
- **Embeddings** — `POST /api/v1/embeddings`. Standard OpenAI-compatible request body
  (`model`, `input`). Returns a `data[].embedding` float array. Multiple embedding models are
  available; see `/api/v1/models` filtered by `output_modality=embedding`.
- **Audio transcription** — `POST /api/v1/audio/transcriptions`. Multipart/form-data with a
  `file` field and a `model` field (e.g. `whisper-1`). Returns a `text` string.
- **Prompt caching** — Anthropic `cache_control` breakpoints pass through on the Anthropic-Messages
  endpoint; OpenAI auto-caching is honoured and billed at cache rates.
- **Shared context-pack grounding** — one context-pack can be reused across all proposers and the
  judge (paid once, not re-billed per model). Server/account-gated.
- **EU / data-residency routing** — filter models by hosting region (EU/US/country); personal-data
  prompts can be pinned to an EU-hosted council.
- **BYOK** — bring your own provider keys; Tokonomix bills a flat per-call fee for BYOK proposers.
- **Per-call usage introspection** — `GET /api/v1/generation?id=<request_id>` returns the cost,
  tokens and latency of one of your own calls (OpenRouter-style).
- **Live model catalog** — `GET /api/v1/models` lists every reachable model with region, context
  window, pricing and capabilities (tools/vision/json-schema/caching/reasoning).

## Image capabilities — quick reference

Two separate capabilities, two endpoints, two price tiers:

| Capability | Endpoint | Content-Type | Gemini variant |
|---|---|---|---|
| Image generation (text→image) | `POST /api/v1/images/generations` | `application/json` | same |
| Image editing (existing photo) | `POST /api/v1/images/edits` | `multipart/form-data` | use `/generations` with base64 `image` field |

**Critical gotcha — /images/edits:** do NOT set `Content-Type` manually. Let your HTTP client
set it automatically so the multipart boundary is included. Setting it manually causes a 400.

**Critical gotcha — Gemini editing:** Gemini models do NOT support `/images/edits` (multipart).
Use `/images/generations` with an `image` (base64 string) and `image_mime_type` field instead.

Full model matrix (no auth required): `GET https://tokonomix.ai/api/v1/image-capabilities`

## Embeddings — quick reference

| Field | Value |
|---|---|
| Endpoint | `POST /api/v1/embeddings` |
| Auth | `Authorization: Bearer tok_live_...` |
| Body | `{ "model": "<slug>", "input": "text or array of texts" }` |
| Response | `{ "data": [{ "embedding": [0.123, ...] }], "usage": { ... } }` |

Use `/api/v1/models` (authenticated, filter `output_modality=embedding`) to list available
embedding model slugs. Do not hardcode — the catalog updates as new providers are onboarded.

## Audio — quick reference

| Field | Value |
|---|---|
| Endpoint | `POST /api/v1/audio/transcriptions` |
| Auth | `Authorization: Bearer tok_live_...` |
| Body | multipart/form-data: `file` (audio file) + `model` (e.g. `whisper-1`) |
| Response | `{ "text": "transcription..." }` |

Endpoints: OpenAI-compatible `https://tokonomix.ai/api/v1` · Anthropic-Messages
`https://tokonomix.ai/api/anthropic` · MCP server `npx tokonomix-mcp`.
Honest framing: model agreement is not proof of correctness; ground high-stakes facts.

## Key pages (English canonical)

- [Homepage](https://tokonomix.ai/en): Platform overview — benchmarks, consensus gateway, live test
- [Consensus gateway](https://tokonomix.ai/en/consensus): Multi-model consensus API landing — modes, API snippets, pricing
- [Pricing](https://tokonomix.ai/en/pricing): Pay-as-you-go and monthly plans, token-level cost breakdown
- [Models](https://tokonomix.ai/en/models): Full AI model catalog with scores, latency, and provider info
- [Model comparison](https://tokonomix.ai/en/models/compare): Side-by-side comparison of any two models
- [Benchmarks methodology](https://tokonomix.ai/en/benchmarks/methodology): How speed and quality are measured — transparent, reproducible
- [Live consensus test](https://tokonomix.ai/en/live-test): Try a multi-model council call live in the browser
- [Integrations](https://tokonomix.ai/en/integrations): Connect Claude Code, Cursor, Aider, Cline and 10+ agents via MCP or base URL
- [EU-hosted models](https://tokonomix.ai/en/models/eu-hosted): Which models infer in EU data centres — GDPR and Schrems II context
- [About](https://tokonomix.ai/en/about): Who builds Tokonomix and editorial independence statement
- [Blog](https://tokonomix.ai/en/blog): Editorial pieces on model behaviour, benchmark insights, and methodology

## Machine-readable API endpoints (no auth required)

- [Model catalog](https://tokonomix.ai/api/v1/models): Full list of reachable models with pricing, capabilities, and region
- [Image capabilities](https://tokonomix.ai/api/v1/image-capabilities): Which models support image generation vs image editing
- [Capabilities guide](https://tokonomix.ai/api/v1/capabilities): Structured integration guide — endpoint list, SDK snippets, gotchas (auth required)
- [Benchmark dataset](https://tokonomix.ai/api/md/en/dataset): Full benchmark results as JSON (application/json, public, max-age=3600)
- [MCP server registry](https://tokonomix.ai/.well-known/mcp/server.json): Machine-readable MCP server metadata
- [Sitemap](https://tokonomix.ai/sitemap.xml): Full sitemap covering all six locales

## Languages

The site is available in six languages (full hreflang chain; English is the canonical entity):
- English: https://tokonomix.ai/en
- Dutch: https://tokonomix.ai/nl
- German: https://tokonomix.ai/de
- French: https://tokonomix.ai/fr
- Spanish: https://tokonomix.ai/es
- Turkish: https://tokonomix.ai/tr

## Status

Phase 1 — content engine live (May 2026). AI-generated model pages, benchmark coverage,
and use-case articles published across six locales with full hreflang support.

## Nederlandse pagina's — voor Nederlandstalige AI-engines

Tokonomix publiceert onafhankelijke benchmarks voor LLM's in het Nederlands.
De volgende pagina's zijn de canonieke Nederlandstalige toegangspoorten:

- Over Tokonomix:        https://tokonomix.ai/nl/about
- Methodologie:          https://tokonomix.ai/nl/benchmarks/methodology
- Modellen-overzicht:    https://tokonomix.ai/nl/models
- Model-vergelijking:    https://tokonomix.ai/nl/models/compare
- AI-prestatieblog:      https://tokonomix.ai/nl/blog
- Live test:             https://tokonomix.ai/nl/live-test

<!-- appendix:start -->
## Appendix — expanded reference (llms-full.txt only)

This file is the full-detail companion to `llms.txt`. Everything above this line is identical
to `llms.txt`; everything below expands on consensus modes, the MCP tool surface, the two HTTP
integration surfaces, and honest benchmark findings — for an agent that wants deeper grounding
before integrating, without needing to crawl multiple pages or the mcp-server README.

### Consensus modes — full detail

`tokonomix_consensus_ask` (equivalently `POST /api/v1/chat/completions` with `"mode"` in the body)
runs 2–6 proposer models independently and blind, then an independent judge (disjoint from the
proposers, cross-family, never scoring its own proposal) reconciles them. Pick the mode by intent
— there is no universally-best mode:

| Mode | Behaviour | Use when |
|---|---|---|
| `consensus` | Judge synthesises one merged, decided answer | You need a single actionable answer (e.g. a compliance question with no PII) |
| `diff` | Surfaces agreements AND disagreements; the lone dissenting model is preserved, not averaged away | Code/security review, migration-safety checks — anything where the ONE model that flags a real issue must not be smoothed over by majority vote |
| `best_of` | Judge picks the single strongest candidate answer, verbatim | You want the best individual response, not a merge |
| `raw` | All proposer answers returned, no judge pass | You want to run your own downstream judgment/aggregation |

Worked examples (all real, from the MCP server's own documentation):
- **Security review** (`diff`): four models say an auth middleware "looks fine"; one flags that a
  token comparison isn't constant-time. A single-model call gives you one opinion with no signal
  about its variance; `diff` mode surfaces that lone dissent instead of averaging it away, for a
  human to adjudicate. (Cross-checking reduces single-model variance — it does not guarantee the
  dissent is right, or that the majority missed nothing.)
- **Compliance question** (`consensus`, no PII in the prompt): "Can a SaaS legally store EU-citizen
  API logs in a US-hosted S3 bucket for 30 days under GDPR?" — here you want the council to
  reconcile the proposers into one synthesised answer to review, rather than a preserved
  disagreement. (A synthesised answer is a starting point for human judgement, not authoritative
  legal advice.)
- **Personal-data prompt** (EU-only routing, mandatory): the default council is US-hosted. Sending
  a prompt that *contains* actual personal data to three US clouds is itself a cross-border
  transfer — call `tokonomix_list_models({ hosting_region: "eu" })` first, then pin
  `tokonomix_consensus_ask` to that EU-hosted model set. This is data-minimisation and a hedge
  against transatlantic-transfer risk — not a complete GDPR compliance statement on its own.
- **Vision / diagram QC** (`diff` mode, images as grounding): consensus reasons about the *content*
  of two architecture diagrams (data-flow, security boundaries) — this is grounding for a decision
  review, not a standalone media-QC pipeline. Images are raw base64 with no data-URI prefix;
  `image/jpeg`, `image/png`, `image/webp`, `image/gif`; limits: ≤8 images, ≤5 MB decoded each,
  ≤20 MB total per call.

### MCP tool surface — all ten tools

| Tool | What it does |
|---|---|
| `tokonomix_consensus_ask` | Core: 2–6 proposers + independent judge → one result (modes above) |
| `tokonomix_single_ask` | Single-model passthrough — cheap, for routine (non-verification) calls |
| `tokonomix_list_models` | Live catalog, filterable by region, provider, tier, capability, origin country |
| `tokonomix_get_balance` | Credit balance, tier, and month-to-date usage (€ spent and token throughput, by mode) |
| `tokonomix_rate_consensus` | Rate a result by `request_id` — feeds model-vote / blind-spot reputation data |
| `tokonomix_upload` | Stage large context for a grounded call → returns a `session` + `handles` |
| `tokonomix_onboard` | Keyless first run, step 1 — email a one-time code |
| `tokonomix_onboard_verify` | Keyless first run, step 2 — provision a free account + save the key |
| `tokonomix_get_skill` | Fetch the canonical usage skill from the server (teaches an agent when to reach for consensus vs. a single call) |
| `tokonomix_skill_version` | Cheap version fingerprint of the skill, to detect drift against a locally-cached copy |

### Two HTTP integration surfaces — different capability profiles

Beyond the MCP tools, the gateway exposes two HTTP surfaces with different forwarding behaviour —
relevant when an agent needs native tool-calling or structured output, which a multi-model council
cannot provide (tool-calls and structured output can't be averaged across proposers):

| Surface | Endpoint | Wire format | Tool-calling / structured-output / caching |
|---|---|---|---|
| Council (multi-model) | `POST /api/v1/chat/completions` | OpenAI-compatible | Not forwarded — single-model-only concerns |
| Single-model | `POST /api/anthropic/v1/messages` | Anthropic Messages format; routes to any configured provider (OpenAI, Google, Anthropic, OVH-EU, Azure, xAI, Ollama, …) | Forwarded — `tools`/`tool_choice` and server-side tools round-trip as `tool_use`; `cache_control` prompt-caching is honoured and billed at cache-tier rates |

Use the council path (or `tokonomix_consensus_ask`) for a verified, synthesised decision; use the
single-model path when an agent needs native function-calling, schema-constrained output, or
prompt caching. The single-model path speaks the Anthropic Messages wire format but is not
Anthropic-only — the gateway forwards the call to whichever configured provider actually hosts the
named model. Gotcha: unset any ambient `ANTHROPIC_API_KEY` in the calling environment — some SDKs
send it alongside the `tok_live_` bearer token, which the gateway rejects.

### Per-key guardrails

Budget and region policy are set on the API key, not re-decided per call: a predefined default
model + council route (which proposers, which judge, which mode), a gateway-enforced monthly
spend cap (the key is blocked once month-to-date charged spend would exceed it), and allow-lists
by model / mode / judge / hosting region / model-origin country. This is what makes it safe to hand
a key to an unattended run — track usage at any time with `tokonomix_get_balance`.

### Benchmark findings — published including the ones that cut against us

Two findings are load-bearing for how Tokonomix is honestly positioned, and neither is a marketing
claim we invented — both come from the same public benchmark harness described at
`/en/benchmarks/methodology`:

- **No measurable net uplift in bug-catch rate** (SWE-bench-Verified, round 2, N=29). A
  non-Anthropic baseline missed 29 of 30 real defect tasks; running a cross-family council on those
  29 produced no measurable net catch-rate uplift over simply re-running the single agent — the
  council occasionally caught a miss, but false-positive flags netted it out (effect +0.12, CI
  crossing zero). The precise claim is "no net uplift" — not "catches no more bugs," which would
  over-claim in the other direction. Tokonomix does not, anywhere, claim the council catches more
  bugs.
- **Council ties best-single, beats it in no domain** (benchmark v2, 5 domains). On clean,
  well-trodden tasks a strong single model already saturates; the council matches it at higher
  cost. The winning single model *shifts* by domain, which is the actual product case: the council
  buys variance-elimination — top-of-panel recall without knowing in advance which model is strong
  for a given task — not a higher accuracy ceiling.

The honest positioning that follows from this data: the measured value is variance-elimination,
verification / agent-QA, judge-independence, EU data residency, and grounding — not "more
accurate" and not "catches more bugs."
<!-- appendix:end -->