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:

FieldTypeNotes
modelstringRequired. Any id from /v1/models.
messagesarrayOpenAI message format (system/user/assistant/tool).
streambooleanEnable SSE streaming. See Streaming.
temperature, max_tokens, top_pnumberStandard sampling parameters.
tools, tool_choiceobjectFunction calling, passed through to the model.
prompt_cache_keystringStable conversation id — also used for sticky routing.
fuelline_trim_responsebooleanTrim 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-id request header (recommended)
  • prompt_cache_key request 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"
  }
}
StatusMeaning
401Missing or invalid API key.
404Unknown model — not in the catalog at all.
502Known 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.

LimitDefaultNotes
Requests per minute5,000Non-streaming and streaming combined.
Concurrent streams500Open SSE streams per key.
Requests per day10,000,000Rolling 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.