Quickstart
Fuelline is a drop-in replacement for the OpenAI API. Get an API key, set the base URL to https://fuelline.dev/v1, and pick any model from the catalog.
curl https://fuelline.dev/v1/chat/completions \
-H "Authorization: Bearer $FUELLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zai-org/GLM-5.3-Flash",
"messages": [{"role": "user", "content": "Hello, Fuelline!"}]
}'Python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://fuelline.dev/v1",
api_key=os.environ["FUELLINE_API_KEY"],
)
response = client.chat.completions.create(
model="zai-org/GLM-5.3-Flash",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)JavaScript / TypeScript
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://fuelline.dev/v1",
apiKey: process.env.FUELLINE_API_KEY,
});
const response = await client.chat.completions.create({
model: "zai-org/GLM-5.3-Flash",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);Authentication
All /v1/* endpoints require a Bearer token in the Authorization header:
Authorization: Bearer fuelline-...
Missing or invalid keys get a 401 with an OpenAI-style error body. Keys are issued by the Fuelline team — contact us to get one.
Chat completions
POST /v1/chat/completions accepts the standard OpenAI request body. Supported fields:
| Field | Type | Notes |
|---|---|---|
model | string | Required. Any id from /v1/models. |
messages | array | OpenAI message format (system/user/assistant/tool). |
stream | boolean | Enable SSE streaming. See Streaming. |
temperature, max_tokens, top_p | number | Standard sampling parameters. |
tools, tool_choice | object | Function calling, passed through to the model. |
prompt_cache_key | string | Stable conversation id — also used for sticky routing. |
fuelline_trim_response | boolean | Trim answer whitespace at the start and end; preserve interior formatting. Works with streaming. Default true; set false to preserve edge whitespace. |
Unknown fields are accepted and forwarded as-is, so model-specific parameters work too.
Answers are trimmed by default: "\n\n391 \n" becomes "391". Set "fuelline_trim_response": false when leading indentation or a final newline must be preserved. This gateway-only option preserves reasoning, tools and reported usage. See API reference for character rules, streaming limits and errors.
Streaming
Set "stream": true to receive Server-Sent Events. The chunk format is identical to OpenAI's, terminated by a data: [DONE] line.
curl https://fuelline.dev/v1/chat/completions \
-H "Authorization: Bearer $FUELLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zai-org/GLM-5.3-Flash",
"messages": [{"role": "user", "content": "Count to five"}],
"stream": true,
"stream_options": {"include_usage": true}
}'Tip: send stream_options.include_usage — the usage object is only emitted in the final chunk when it's requested, and it's required for accurate token accounting.
Failover happens before the first token is committed. Once streaming starts, the response is never re-routed mid-stream (that would duplicate tokens).
Sticky sessions
Requests with more than 32,000 prompt characters can reuse the same eligible provider within a conversation, helping preserve upstream prompt caches. The sticky key is resolved in order:
x-session-idrequest header (recommended)prompt_cache_keyrequest field- hash of the first two messages
Prompt length includes text across the full message history and tool definitions/calls; media data and URLs do not count. Smaller requests use normal provider selection and do not create or renew affinity. Routes are saved after successful delivery and expire 10 minutes after the last successful eligible large request. Temporary routing constraints do not create or renew affinity. Single-message requests without a session or cache key get no sticky route. Provider affinity does not guarantee an upstream cache hit.
curl https://fuelline.dev/v1/chat/completions \
-H "Authorization: Bearer $FUELLINE_API_KEY" \
-H "x-session-id: my-conversation-123" \
-H "Content-Type: application/json" \
-d '{ "model": "zai-org/GLM-5.3-Flash", "messages": [...] }'Failover & errors
If a serving route fails (error, timeout, rate limit), Fuelline retries the request on the next best route — up to 4 attempts per request, never revisiting a failed one. Routes in cooldown are probed only when no healthy one remains.
Errors follow the OpenAI shape:
{
"error": {
"message": "All routes failed for model zai-org/GLM-5.3-Flash",
"type": "server_error",
"code": "timeout"
}
}| Status | Meaning |
|---|---|
401 | Missing or invalid API key. |
404 | Unknown model — not in the catalog at all. |
502 | Known model, but every route failed (or all are down). |
In streaming mode a terminal failure is delivered as an SSE error event with the same error object.
Rate limits
Operational limits per API key. These describe the sustained load each key is provisioned for; traffic far above them may be throttled with a 429 (OpenAI-style error body) to protect other clients.
| Limit | Default | Notes |
|---|---|---|
| Requests per minute | 5,000 | Non-streaming and streaming combined. |
| Concurrent streams | 500 | Open SSE streams per key. |
| Requests per day | 10,000,000 | Rolling 24-hour window. |
Higher limits are available on request — keys issued for aggregator integration can be provisioned individually. If you need more headroom, contact us with your expected request rate and peak concurrency.
Listing models
GET /v1/models returns the routable catalog, same shape as OpenAI:
curl https://fuelline.dev/v1/models \ -H "Authorization: Bearer $FUELLINE_API_KEY"
The public catalog with prices is also available without a key at GET /public/models — it powers the pricing table on the home page.