API reference

FluxRouter is an OpenAI- and Anthropic-compatible gateway. Point an existing OpenAI or Anthropic client at the FluxRouter base URL with your Flux key, and it works. If you are connecting an agent rather than writing code, start at Connect your agent.

Base URLs#

These are not interchangeable. Giving an Anthropic client the OpenAI base produces /v1/v1/messages, which returns 404.

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 accepts the same key either way: Authorization: Bearer sk-... or the x-api-key: sk-... header the Anthropic SDKs send by default. The ability endpoints accept both too, except GET /v1/audio/voices and the MCP servers, which read only Authorization: Bearer.

If you limited a key to certain models, the ability endpoints check that list as well: add the ability's model names (such as flux-voice or flux-image) to the key, or its calls are refused with 401 or 403.

Endpoints#

Models#

Abilities#

Each endpoint has its own reference page with every field, the response, the headers and the errors.

An ability endpoint that is not switched on for your account answers 404. The second opinion is not an endpoint: it is a flag on a flux-auto chat call. See Second opinion. Apps have no endpoint of their own: they are reached through the tools server. How to call each ability from an agent is under Give your agent abilities. Prices are on the pricing page; speech, transcription and image prices are also in the models list.

MCP#

Both authenticate with the same sk- key as a bearer token.

There is no bare /chat path. 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.

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.

The ability endpoints differ:

Model aliases#

Set the model field to one of these:

See Models for pinned ids and How routing works 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 set of flux-* ids you can use in the model field. Use it instead of hard-coding a model list.

Response headers#

Chat responses carry X-Flux-* headers so you can see what the router did:

X-Flux-Original-Model is the alias you asked for, such as flux-auto; X-Flux-Routed-Model is the model that answered.

The model and lane headers above come back on non-streaming responses. A streamed response carries only X-Flux-Alias; the model that answered is in your Activity page.

On a streamed response the cost arrives in the final usage block instead. See Receipts.

Ability responses carry their own receipt headers:

Errors#

FluxRouter returns standard HTTP status codes with an OpenAI-compatible JSON error body. The common cases:

Every 402 carries a machine-readable refusal code. The full list, where each code is carried, and how to handle it are in the chat error reference.

The ability endpoints and the MCP servers use a few other error shapes. Every shape and every ability code is in the error reference for every endpoint and tool.

Quick requests #

The fastest way to check that a key works is a raw HTTP request: no SDK, no config file, just the base URL and a bearer token.

curl https://api.fluxrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-FLUX-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-auto","messages":[{"role":"user","content":"hi"}]}'

A JSON response with a choices array means your key and endpoint are live, and the request shows in your dashboard.

Add "stream": true to get tokens as they arrive, as server-sent events:

curl https://api.fluxrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-FLUX-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-auto","stream":true,"messages":[{"role":"user","content":"hi"}]}'

The same call on the Anthropic path:

curl https://api.fluxrouter.ai/anthropic/v1/messages \
  -H "x-api-key: sk-YOUR-FLUX-KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-auto","max_tokens":256,"messages":[{"role":"user","content":"hi"}]}'

Add -i to any of these to see the X-Flux-* response headers.

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"}],
)

Because FluxRouter speaks the OpenAI and Anthropic wire formats, most tools that already talk to either work by changing only the base URL and the key.