An LLM gateway with the data layer attached

Six endpoints, not one

Everything under /api/v1 is a model call, but the model kind decides which endpoint can answer — and each endpoint returns its own format.

The three chat surfaces are native implementations, not a translation layer: each streams events in its own protocol, so you parse the stream exactly as you do today.

Pick the endpoint by model kind, not by guesswork

Every model in the catalog carries a model_kind, and the kind decides which endpoint can call it. Discovery costs nothing and reads the local catalog.

# discover before you call — free, reads the catalog
GET /api/v1/models   # every kind, with channels and rates
GET /api/v1/models/{model_id}  # one model, in detail
GET /api/v1/videos/models     # video_generation only
GET /api/v1/decisions/models  # decisions only

Filter with ?provider= to see one supplier's list, or ?exclude_video_and_decisions=true to hide everything but chat and image. A listing is not a promise: a video model will not answer a chat request, and the API answers model_kind_mismatch when you try.

Default route, or one header to pick the provider

A model can be served by several upstream channels, each with its own supplier and its own published rate. Leave the header off and the platform picks one for you; send X-Felo-Channel and you choose.

# first channel only — no automatic fallback
X-Felo-Channel: claude-cc
X-Felo-Channel: claude-cc,anthropic  # ordered selection, not a retry list

• The value is an ordered list of public channel codes taken from the model's channels[].code, validated in the order you write them.
• Only the first channel's provider group is submitted, and that channel's rate is what you pay.
• There is no automatic fallback. A channel list is a selection, not a retry policy — if a provider fails, resend from your application with another channel.

X-Felo-Channel works on all six generation endpoints above. It does not apply to the Data API or the Felo APIs: those go to the supplier you name in the request.

What a call actually costs

Model calls bill per token — input, output and cache — with the channel's discount multiplier applied. Rates are published per 1M tokens for readability, but billing uses the per-token precision in the current price snapshot, so a short request is never rounded up to a million.

• Cache rates apply only when the protocol response reports cache usage; a model without cache reporting bills everything at its input rate.
• Web search that a model service performs and reports costs $0.01 per search.
• Some models tier by prompt size: Claude Haiku 5.5 bills $0.10 in and $0.50 out per 1M tokens up to a 100K-token prompt, then $0.50 and $2.50 for the whole request above that.
• The first top-up is $1. There is no subscription, no seat fee and no minimum commitment — an idle key costs nothing.

Data API calls and Felo workflows bill from the same balance, each on its own published basis: per successful request, per returned item, or by actual usage.

Two limits that look alike and are not

Running out of credits returns 402 INSUFFICIENT_CREDITS. Calling too fast returns 429 RATE_LIMITED. Waiting clears the second and never clears the first.

Only /v2/chat documents enforced rate limits today. Model calls can still be limited upstream, which surfaces as a 429 — read X-RateLimit-* and Retry-After instead of hardcoding numbers. Every response carries a request_id, and an X-Request-Id header you send is echoed back, so your logs and ours line up.

Image and video finish in the background

Both generation endpoints return a task_id instead of a result. Submit, poll, retrieve — and note that once a task exists, most failures arrive as a 200 with a terminal status rather than as an HTTP error.

# submit, then poll the task
POST /api/v1/images/generations       → task_id
GET  /api/v1/images/generations/{id}  → status, result
POST /api/v1/videos/generations       → task_id
GET  /api/v1/videos/generations/{id}  → status, result

Read the status before you read the output: failed and interrupted are answers too, and error.message says why. A 402 at submit time means the task was never created. SuperAgent works differently — it hands back a stream_key and pushes events over SSE, so there is nothing to poll.

Change the base URL, keep the client

Both SDKs work unchanged once the base URL points here. npx feloapi-cli setup writes the same configuration for Claude Code and Codex.

# OpenAI SDK
base_url = "https://openapi.felo.ai/api/v1"

# Anthropic SDK — one level up; the SDK appends /v1/messages
base_url = "https://openapi.felo.ai/api"

# pin a provider (optional)
default_headers = {"X-Felo-Channel": "claude-cc"}

Model IDs are not identical across providers. Pick from the catalog before you flip the base URL, or your first call answers 404.

The half a gateway usually leaves to you

An LLM gateway routes model calls. Here the same key also reaches a catalog of ⁦5,000+⁩ APIs — so the search step in your agent, the deck it generates and the document it reads back are billed to the same credits, not to three more vendors.

• Search
• PPT Task
• SuperAgent
• Web Fetch
• X Search
• Mindmap
• Landing Page Task
• LiveDoc
• YouTube Subtitling

Data API calls go to named providers under /v1/beta — Tavily, Exa, Apollo and the rest of the catalog — each at its own published basis.

LLM gateway questions, answered