Cradler
Cradler Router · API

Cradler Router API

Point any official SDK's base URL at Cradler Router and call Claude, GPT, Gemini, and image models without changing your code. Router speaks the Anthropic, OpenAI, and Gemini formats natively.

Base URL: https://router.cradler.ai
Auth: your Router API key (sk-…)
Protocols: Anthropic Messages, OpenAI Chat Completions (every model), OpenAI Responses (GPT only), native Gemini, and image generation.

Keep your key in an environment variable or secrets manager — never commit it or ship it in a client bundle.

Base URL and headers

Auth headers differ by protocol. OpenAI SDKs expect the base URL to include /v1; the Anthropic SDK does not.

ProtocolAuth header
Anthropicx-api-key: sk-… + anthropic-version: 2023-06-01
OpenAIAuthorization: Bearer sk-…
GeminiAuthorization: Bearer sk-… (or x-goog-api-key)

Listing models

GET/v1/models

Fetch the live list your key can reach. Always read this rather than hard-coding an ID — models are added and retired over time.

bash
curl https://router.cradler.ai/v1/models \
  -H "Authorization: Bearer sk-…"

Anthropic format — messages

POST/v1/messages

The endpoint for Claude models — also what Claude Code uses. Claude works over the OpenAI format too, but prefer this one where you can: it keeps prompt caching and thinking.

bash
curl https://router.cradler.ai/v1/messages \
  -H "x-api-key: sk-…" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Introduce yourself in one sentence." }
    ]
  }'

Streaming: add "stream": true for a text/event-stream response. Tool use works through the gateway: declare tools, and the model returns tool_use blocks you answer with tool_result.

python
# anthropic SDK
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-…",
    base_url="https://router.cradler.ai",   # note: no /v1 for the Anthropic SDK
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content[0].text)

OpenAI format — chat & responses

POST/v1/chat/completions
POST/v1/responses

Chat Completions carries the entire catalog — Claude and Gemini included — so a tool that only speaks the OpenAI format still reaches every model behind one key. The Responses API (/v1/responses) is the GPT-series agent protocol — it is what Codex uses, and it stays GPT-only.

bash
curl https://router.cradler.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-…" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
python
# openai SDK (Responses API)
from openai import OpenAI

client = OpenAI(
    api_key="sk-…",
    base_url="https://router.cradler.ai/v1",   # OpenAI SDK includes /v1
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="Summarize this repo's architecture.",
)
print(resp.output_text)

Fast mode: add service_tier: "fast" for higher-priority processing on supported GPT models — up to ~2.5x speed, billed at ~2x the standard rate. The Responses API serves GPT only — send Claude and Gemini to /v1/chat/completions, which carries every model in the catalog.

Gemini format — generateContent

POST/v1beta/models/{model}:generateContent
bash
curl "https://router.cradler.ai/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-…" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Introduce yourself in one sentence." }] }
    ]
  }'

Stream with streamGenerateContent?alt=sse. If your SDK supports a custom endpoint, point its base URL at https://router.cradler.ai and use Bearer auth (GEMINI_API_KEY_AUTH_MECHANISM=bearer).

Image generation

POST/v1/images/generations
POST/v1/images/edits

Image models use the OpenAI-compatible images endpoints. Set a generous client timeout (~300s) — generation can take a while.

bash
curl https://router.cradler.ai/v1/images/generations \
  -H "Authorization: Bearer sk-…" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "an orange cat typing on a keyboard, flat illustration"
  }'
# Response: data[0].b64_json holds the base64 image.
# Editing: multipart upload to /v1/images/edits with an image + prompt.

Using it in agent tools

Claude Code speaks Anthropic, Codex speaks OpenAI, Gemini CLI speaks Gemini. Point the base URL and key at Router — no change to the tools themselves.

bash
# Claude Code (Anthropic)
export ANTHROPIC_BASE_URL="https://router.cradler.ai"
export ANTHROPIC_AUTH_TOKEN="sk-…"

# OpenAI-based tools (Chat Completions / Responses)
export OPENAI_BASE_URL="https://router.cradler.ai/v1"
export OPENAI_API_KEY="sk-…"

# Gemini CLI
export GOOGLE_GEMINI_BASE_URL="https://router.cradler.ai"
export GEMINI_API_KEY="sk-…"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

Step-by-step guides: Claude Code, Codex, Gemini CLI.

Usage and billing

Query token usage, cost, and balance for your key. Use these to reconcile spend and monitor your balance.

EndpointReturns
GET /v1/billing/balanceCurrent account balance
GET /v1/billing/requests/{id}Token usage & cost for one request
GET /v1/usage?start_time&end_timeToken usage over a range (≤ 90 days)
GET /v1/billing/costs?start_time&end_timeBilled amount over a range (≤ 90 days)
bash
curl https://router.cradler.ai/v1/billing/balance \
  -H "Authorization: Bearer sk-…"
# { "balance": { "value": "85.32", "currency": "USD" } }

Rate limits

Rate limits cap how many requests you can make per unit of time. Free models (IDs ending in -free) are limited; paid models have no account-level rate limit.

Model typeLimit
Free models (e.g. deepseek-v4-flash-free)50 requests/day for all users — resets daily
Paid models (e.g. deepseek-v4-flash)No account-level rate limit

When the free daily quota runs out, switch to the paid version of the model. On a 429 rate_limit_exceeded, back off and retry with exponential backoff.

Troubleshooting

401 / auth failed: match the header to the protocol — Anthropic uses x-api-key, OpenAI and Gemini use Authorization: Bearer. The OpenAI base URL includes /v1; the Anthropic one does not.

Claude and Gemini over the OpenAI format: /v1/chat/completions accepts every model, so OpenAI-only tools reach the whole catalog. Prefer the native protocols when your tool supports them — /v1/messages for Claude, the Gemini endpoint for Gemini — since the translation layer gives up provider-specific features like prompt caching controls and extended thinking. /v1/responses stays GPT-only and answers 404 for anything else, naming the endpoint to call instead.

Model unavailable: confirm the exact ID with GET /v1/models (all lowercase; mind dots vs dashes).

Slow first token: large models can take seconds before the first token — normal, not a failure. Use streaming and a generous read timeout in production.

One-command setup

The fastest path for the CLI agents below: one command writes every config and verifies your key live.

One command, every agent

Paste your key, copy the command, run it in a terminal. It writes the config for Claude Code, Codex, and Gemini CLI — plus OpenClaw, ZCode, and Cherry Studio when they're installed — then verifies your key against the Router. Built locally; the key never leaves this page.

npx @cradler/router-setup <your-router-key>

Claude Code

Claude Code speaks the Anthropic Messages API, and Router is a 1:1 compatible endpoint — two environment variables and nothing else changes. Tool use and prompt caching pass through.

bash
export ANTHROPIC_BASE_URL="https://router.cradler.ai"
export ANTHROPIC_AUTH_TOKEN="<your-router-key>"

# Run Claude Code as usual
claude

Pass --model claude-sonnet-4-6 (or any ID from GET /v1/models) to pick a model. Full guide with pricing and FAQ: Claude Code on Router.

Codex

Codex speaks the OpenAI Responses API. Define a provider in ~/.codex/config.toml with wire_api = "responses":

toml
# ~/.codex/config.toml
model = "gpt-5.5"
model_provider = "cradler"

[model_providers.cradler]
name = "Cradler Router"
base_url = "https://router.cradler.ai/v1"
wire_api = "responses"
env_key = "CRADLER_ROUTER_KEY"
bash
export CRADLER_ROUTER_KEY="<your-router-key>"

# Run Codex as usual
codex

The agent loop — shell commands, file edits — passes through unchanged. Full guide: Codex on Router.

Gemini CLI

Gemini CLI talks the native Gemini API; Router exposes it at the same paths. Three environment variables:

bash
# Point Gemini CLI at Cradler Router
export GOOGLE_GEMINI_BASE_URL="https://router.cradler.ai"
export GEMINI_API_KEY="<your-router-key>"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

# Run Gemini CLI as usual
gemini

Streaming works via streamGenerateContent?alt=sse. Full guide: Gemini CLI on Router.

Cherry Studio

No config files here — paste your key and Cherry Studio pops its confirmation dialog with everything pre-filled, via its official cherrystudio:// deep link.

One-click configure

Paste your Router key and click — Cherry Studio opens its confirmation dialog with the provider, API address, and key pre-filled. The link is built locally; your key never leaves this page.

Manually: add a provider of type OpenAI with API address https://router.cradler.ai/v1 and your key, then fetch the model list. For Claude, add a second provider of type Anthropic with address https://router.cradler.ai (no /v1). Full guide: Cherry Studio on Router.

DeepSeek Harness (dsh)

DeepSeek's open-source agent harness reads providers from $DSH_HOME/settings.yaml. Its custom providers speak the OpenAI protocol, which reaches every model on Router — Claude and Gemini included. The one-command setup writes this block for you when dsh is installed.

yaml
# $DSH_HOME/settings.yaml
llm-pi-ai:
  providers:
    cradler:
      apiKeyEnv: CRADLER_ROUTER_KEY
      api: openai-completions
      baseURL: https://router.cradler.ai/v1
      models:
        - id: gpt-5.5
        - id: claude-sonnet-4-6
        - id: gemini-3.6-flash
        - id: deepseek-v4-pro

Export the key before starting dsh — export CRADLER_ROUTER_KEY="sk-…" — so no secret is stored in the settings file. Then run dsh web and pick cradler as the provider.

There is also a plugin, @cradler/dsh-plugin, which registers Router as a first-class provider and reads your model list live, so a model added to your account shows up without editing YAML:

bash
# Install into the profile you boot
dsh plugin --profile web add @cradler/dsh-plugin
export CRADLER_ROUTER_KEY="<your-router-key>"

# Then enable it in $DSH_HOME/cordis.patch.yml:
#   - id: cradler-router
#     name: '@cradler/dsh-plugin'

Keep reading

Cradler Router overview

What Router is and which models and agents it covers.

Router pricing

Per-token rates for every model, USD per 1M tokens.

Claude Code setup

Two environment variables to run Claude Code on Router.

What Cradler includes

Database, file storage, typed SDK, and MCP server.

Get a Router key

Create a Cradler account, top up by card, and start calling every major model through one endpoint.

Start free