Cauce — LLM Router

1Create your account

2Get your API key

After signup, your API key is shown once. Copy it and store it safely — it starts with cau_live_.

Important: Your API key is only shown once during signup. If you lose it, you'll need to create a new one from the dashboard.

3Make your first request

Cauce exposes an OpenAI-compatible API. Use any OpenAI SDK or send a raw curl:

curl https://api.cauce.me/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      { "role": "user", "content": "Hello, world!" }
    ]
  }'

With Python (openai SDK):

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cauce.me/v1"
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

With TypeScript (openai SDK):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.cauce.me/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Hello!" }],
});

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

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the dashboard.

Include this header in every request:

Authorization: Bearer cau_live_...

API keys: plan vs pay-as-you-go

Each API key has a billing mode that you pick when you create it in the dashboard. The mode decides how the request is paid for — a key never mixes both.

Plan key

Uses your plan's request quota. Only the model tiers your plan includes are allowed. It never touches your wallet balance. Best for steady, predictable usage.

Pay-as-you-go key

Charges your wallet balance on every request. Any model is allowed, with no quota or tier limit. Keep a positive balance to use it. Best for occasional or high-tier usage.

If you get a 403 "model_not_in_plan", the model isn't in your plan tier: either upgrade your plan or create a pay-as-you-go key. If you get a 402, top up your wallet balance.

Identify your app (optional)

Send the X-Cauce-App header to label which app or project made each request. The label shows up in your Usage view, so a single API key shared across several apps (e.g. a chatbot and a device manager) stays clearly separated. Compatible with OpenRouter's X-Title header — if you already send that, it works too.

Add this header (max 64 characters):

X-Cauce-App: my-chatbot

Examples by language:

# curl
curl https://api.cauce.me/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Cauce-App: my-chatbot" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

# Python (OpenAI SDK)
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cauce.me/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={"X-Cauce-App": "my-chatbot"},
)

// TypeScript (OpenAI SDK)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.cauce.me/v1",
  defaultHeaders: { "X-Cauce-App": "my-chatbot" },
});

The label is optional and free-form. Leave it out and the request is recorded with no app name.

Attribute usage per end-user

Send the OpenAI-standard `user` field to identify the end-user behind each call. Essential when many users share one API key (a system key): without it, all users' usage is lumped together; with it, the dashboard breaks down and filters cost per end-user.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    user="end-user-123",   # OpenAI-standard: attributes usage to this end-user
)

Tip: use a dotted X-Cauce-App name (e.g. myapp.slides.generation) to encode a hierarchy — the dashboard groups by the full name and you can roll up by prefix to see cost per feature.

Per-petition cost: send the X-Cauce-Trace-Id header with one id per user action, repeated on every call your agent makes for it — the dashboard groups the whole chain and shows cost per petition (and the average).

Streaming

Set stream: true to receive responses as Server-Sent Events (SSE). Each chunk contains a delta of the response.

data: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":" world"}}]}

data: {"choices":[{"delta":{"content":"!"}}]}

data: [DONE]

Streaming example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cauce.me/v1"
)

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Images (vision)

Models that accept images use the same /v1/chat/completions endpoint and the standard OpenAI content-block format — a list of blocks instead of a plain string. No separate endpoint, no separate SDK.

To find which models take images, call GET /v1/pricing: a vision model lists "image" under capabilities.input. GET /v1/models returns ids only and does not carry capabilities.

Python — inline base64

python

import base64
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cauce.me/v1"
)

with open("invoice.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Extract the total and the date."},
            {"type": "image_url",
             "image_url": {"url": f"data:image/jpeg;base64,{b64}"}},
        ],
    }],
)

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

Or reference the image by URL — accepted by some models only (celeris-1, for one, takes inline base64 exclusively)

json

{"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}}

Several images in one request

Add more image_url blocks to the same message. One request, one context — the model can compare them.

Images go in user messages

Providers reject images placed in a system or assistant message. Put the instruction and the image in the same user message.

Size limit

The whole request body is capped at 32 MiB. base64 inflates a file by about a third, so prefer smaller images — and where the model accepts remote URLs, send large ones that way.

An image is never dropped in silence

Sending an image to a text-only model returns 400 model_does_not_support_image. It is never ignored, because a model that answers about a picture it never received sounds correct and is not.

Request Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model ID from /v1/models or /v1/pricing
`messages`	array	Yes	Array of message objects with role and content
`stream`	boolean	No	Enable streaming responses (default: false)
`temperature`	number	No	Controls randomness, 0-2 (default: 1.0)
`max_tokens`	integer	No	Maximum tokens in the response
`top_p`	number	No	Nucleus sampling alternative to temperature
`stop`	string/array	No	Sequences where the model stops generating

Rate Limits

60 requests per minute per API key. Exceeding the limit returns HTTP 429 with a Retry-After header.

The rate limiter fails open: if Redis is unavailable, requests proceed normally.

Error Codes

Code	Meaning	Details
`400`	Bad Request	Malformed request. Includes model_does_not_support_image when a request carries an image for a text-only model.
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient wallet balance — top up to continue
`403`	Forbidden	Model not on your plan tier — upgrade your plan or use a pay-as-you-go key
`413`	Payload Too Large	request_too_large — the body exceeds 32 MiB. Send fewer or smaller images, or reference them by URL.
`429`	Rate Limited	Too many requests or plan quota exhausted — check the Retry-After header
`503`	Service Unavailable	All providers unavailable — try again later

Response Format

Every response includes the standard OpenAI-compatible body plus a cauce_meta field with routing and billing info.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "cauce_meta": {
    "model_actual": "deepseek-v4-flash",
    "provider": "deepseek",
    "cache_hit": false,
    "cost_usd": 0.00004
  }
}

Available endpoints

POST

/v1/chat/completions

Chat completions (OpenAI-compatible). Supports streaming.

GET

/v1/models

List available models.