Reference
API reference for FluxRouter: endpoints, authentication, model aliases, the models list, response headers, and error handling.
FluxRouter is an OpenAI- and Anthropic-compatible gateway. Point an existing OpenAI or Anthropic client at the FluxRouter base URL and your Flux key, and it works.
Base URL
https://api.fluxrouter.ai
Authentication
Pass your Flux API key (sk-...) as a bearer token on every request:
Authorization: Bearer sk-...
One key works across every endpoint and model. Keep it secret; it is tied to your account's billing and spend ceiling.
The Anthropic-compatible endpoint (POST /anthropic/v1/messages) accepts the same key either way: Authorization: Bearer sk-... or the x-api-key: sk-... header that the Anthropic SDKs send by default. You do not need to change how your Anthropic client passes its key.
Endpoints
| Method | Path | Wire format | Purpose |
|---|---|---|---|
| POST | /v1/chat/completions | OpenAI Chat Completions | Primary chat endpoint |
| POST | /v1/responses | OpenAI Responses API | Responses-style requests |
| GET | /v1/models | OpenAI model list | List available flux-* models |
| POST | /anthropic/v1/messages | Anthropic Messages | Anthropic-compatible chat |
| POST | /anthropic/v1/messages/count_tokens | Anthropic | Count tokens for a request before sending it |
| POST | /mcp | MCP | Model Context Protocol endpoint |
There is no bare /chat path. The OpenAI chat path is /v1/chat/completions. For OpenAI clients, set the base URL to https://api.fluxrouter.ai/v1. For Anthropic clients, set the base URL to https://api.fluxrouter.ai/anthropic.
The Anthropic path serves only /anthropic/v1/messages and /anthropic/v1/messages/count_tokens. Other Anthropic routes return 403. Send the anthropic-version header (default 2023-06-01); any anthropic-beta header you set is forwarded upstream.
Streaming
Every chat endpoint streams. Set "stream": true in the request body to receive server-sent events; omit it (or set false) for a single JSON response. GET /v1/models and count_tokens are always non-streaming.
Minimal request
curl https://api.fluxrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $FLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-auto",
"messages": [{ "role": "user", "content": "Hello" }]
}'
Drop-in with the OpenAI SDK
from openai import OpenAI
client = OpenAI(
base_url="https://api.fluxrouter.ai/v1",
api_key="sk-...",
)
client.chat.completions.create(
model="flux-auto",
messages=[{"role": "user", "content": "Hello"}],
)
Model aliases
Set the model field to one of these:
| Alias | Behavior |
|---|---|
flux-auto | Smart routing. The default. Right-sizes each request. |
flux-fast | Lightweight, latency-sensitive tier. |
flux-standard | General-purpose tier. |
flux-reasoning | Stronger tier for harder problems. |
flux-image | Image generation. |
flux-pinned-* | Pin one specific backing model (for example flux-pinned-claude-sonnet). |
See Models for the full pinned list and Routing & pricing for how flux-auto decides.
Listing models
curl https://api.fluxrouter.ai/v1/models \
-H "Authorization: Bearer $FLUX_API_KEY"
GET /v1/models returns the live, authoritative set of flux-* ids you can use in the model field. Use it instead of hard-coding a model list.
Response headers
Chat completion responses include X-Flux-* headers so you can see what the router did:
| Header | Meaning |
|---|---|
X-Flux-Model | The model that actually served the request |
X-Flux-Original-Model | The model id you requested |
X-Flux-Routed | true or false: whether the router changed the model |
X-Flux-Request-Id | Unique request id for support and debugging |
X-Flux-Cost-Usd | What the request cost in USD (non-streaming responses) |
Include X-Flux-Request-Id when contacting support about a specific request.
Errors
FluxRouter returns standard HTTP status codes. Error bodies follow the OpenAI-compatible JSON error shape (an error object with a message). Common cases:
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 402 | Account spend ceiling reached (free tier $1 hard stop, or the account's monthly ceiling) |
| 429 | Rate limited; slow down and retry with backoff |
| 5xx | Upstream or gateway error; retry transient failures with backoff |
A 402 means billing, not a bad request: the account hit its monthly spend ceiling. Free accounts stop at a $1 hard cap; paid accounts have a ceiling that rises with cleared spend and account age.
Compatibility note
Because FluxRouter speaks the OpenAI and Anthropic wire formats, most tools that already talk to OpenAI or Anthropic work by changing only the base URL and API key. Set model to flux-auto (or a flux-* id) and you are done.