Developer documentation

Point the SDK at https://api.flintbeam.com/v1 and send the key as Authorization: Bearer sk-live-…. Keys start with sk-live- and are shown in full exactly once, when created; afterwards the console shows only the first characters. Code written against https://flintbeam.com/v1 keeps working — that address forwards to the same gateway.

Nothing you send in a request is written to disk on the way — only files you upload to /v1/files are kept. See Data and privacy.

The body is OpenAI's. What the gateway reads itself, and what it only carries to the provider:

• model and messages are required; roles are system, user, assistant and tool.
• Send the body as JSON, up to 32 MB with any attachments inside it. A body that is one JSON object is read as JSON even when the Content-Type header is missing or says text/plain.
• max_tokens limits the answer and sizes the reservation taken from your balance before the call. Providers almost always keep this limit, but occasionally return slightly more tokens than max_tokens, and you are charged for the tokens the provider reports. On OpenAI's thinking models it is also raised when it is too small to buy an answer at all: those models pay for their reasoning out of this same allowance, and measured through this gateway, gpt-5-mini and o4-mini each returned an empty string at 2 000 tokens and a real answer at 4 000. How far it is raised depends on what the model costs, not on a fixed number of tokens: the floor is whatever a cent and a third buys at that model's output price, never below 4 000 and never above 32 000. On gpt-5-nano, which returned nothing at all until 16 000, that works out to the full 32 000 for about a penny; on the dearest reasoning models the same budget buys a few dozen tokens, so they keep 4 000 and nothing changes for them. Where the ceiling is raised the reply carries x-ceiling-raised and x-ceiling-reason: thinking_floor, and the reservation is sized against the raised number. Send no max_tokens and the gateway picks one per model: what a fixed budget buys at that model's output price, never below a floor and never above the model's own limit — so a cheap model keeps its whole length and only the expensive ones are shortened. Each model's page shows its own number, /v1/models reports it as default_max_tokens, and every answer carries the number that was really used in the x-ceiling-used header. Tired of writing the line in every call? Set it once on the key, for everything or model by model.
• tools and tool_choice work on every maker's models: passed as they are to OpenAI's, converted into the maker's own shape for the others. response_format goes to the models that take it; on Claude, a json_schema becomes Anthropic's structured output.
• Images in: send image_url content parts — a URL or a data: URL — to a model the catalogue marks as seeing images. Providers that use another shape get the part converted by the gateway.
• Documents: Word, Excel, PowerPoint, OpenDocument, EPUB (.epub) and plain-text attachments are read as text on chat, Responses and Messages. EPUB includes the title and chapters in reading order. Layout and pictures are omitted. Encrypted (DRM), malformed or empty EPUBs are refused with invalid_request (400). At most 4 MB of text is read per document and 8 MB per request; omitted text is marked. The hold counts the extracted text, and x-documents-read names the files read.
• Links: a web page your message links to is read for the model and billed as the tokens it holds, and Gemini also watches a public YouTube video you link to. A link alone never runs a paid search. Links inside attached files are not followed.
• temperature, top_p, stop and the other tuning knobs go through as sent, with the exception described under Parameters we adjust. A knob a model cannot use is ignored rather than refused, and named in the x-ignored-params response header. n above 1 is accepted on OpenAI models (up to 128) and Gemini models (up to 8), and every answer is billed; Claude models refuse it. prediction (Predicted Outputs) reaches the OpenAI models that take it; as at OpenAI, predicted tokens the model rejects are billed as output. On Gemini, detail: "low" on every picture, or Google's own google.media_resolution, has the model look at pictures in low resolution, for far fewer tokens. On OpenAI's models service_tier picks the lane: flex (slower, cheaper), fast (OpenAI's former priority) and, on gpt-6-astra and gpt-6.1-sol, ultrafast. On Gemini it picks Google's lanes: flex on the Gemini 3 Flash and Flash-Lite models, priority on the Gemini text models. Each lane costs the maker's own price for it less 30% where we serve it from capacity we already hold, and the maker's full price where the maker's own account serves it, billed by the lane the answer says it ran on (service_tier in the answer), never above the lane you asked for. A dearer lane a model has no price for here is refused with 400.

A single call may run for up to 600 seconds. Past that it ends with request_timeout.

Pro models and reasoning.mode "pro" may think for up to 30 minutes. Set your client's timeout to at least that (OpenAI and Anthropic SDKs default to 10 minutes). If your client gives up earlier, the answer is still generated and billed.

With stream: true the answer arrives as data: frames in OpenAI’s chunk shape and ends with data: [DONE]. Set stream_options: {include_usage: true} to receive the billed token counts in a final chunk with empty choices, immediately before [DONE]. Without this option, no usage chunk is sent. Keep x-request-id to find the charge in the usage log, including when a stream is interrupted before its final chunk. If the provider breaks mid-answer, an error frame is written into the stream, because the status code has already been sent.

POST /v1/images/generations with model and prompt. size and quality reach the providers that understand them; n is 1 to 10 on OpenAI's models and 1 on Google's, which draw one picture per call. On OpenAI's models, stream: true with partial_images (0 to 3) sends rough drafts while the picture is drawn; as at OpenAI, each draft is billed as 100 output tokens.

The answer is data[0].b64_json: the image as base64, never a URL. Decode it and store it yourself; the gateway keeps nothing. A model that both talks and draws can be asked at /v1/chat/completions instead, and then the picture comes back on the message itself, as choices[0].message.images[0].image_url.url — a data: URI, streamed as an images delta when you stream. A client library that does not know the field ignores it.

A picture is billed at the price on the model's page. A plan pays for it only if it is a money plan that lists that model — daily-ration plans never do — so otherwise it comes from your balance. The gateway waits up to 300 seconds for one.

Example

curl https://api.flintbeam.com/v1/images/generations \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/gemini-3-pro-image", "prompt": "a lighthouse at dawn, watercolor"}'

# Python (openai package):
# img = client.images.generate(model="…", prompt="…")
# open("out.png", "wb").write(base64.b64decode(img.data[0].b64_json))

GET /v1/models returns the models this key may call, in OpenAI's list shape, with each model's default_max_tokens and pricing. Use the ID exactly as the Model Catalog shows it, vendor/model — for example google/gemini-2.5-flash. Prices per 1M tokens are in the catalogue and on each model's page; pricing carries the same prices per unit the model is billed in, so your code can work out what a request cost from its usage.

Each model in the catalogue carries a badge that says which tier it is in: “Economy”, our lower-priced tier, which at busy times can briefly be unavailable, or “Standard”, at the maker's list price and always available. Prices are on each model's page and are never above the maker's list price. If a provider fails, the request is retried automatically.

Send max_tokens. Where a provider insists on max_completion_tokens instead, the gateway renames it — you do not have to know which models those are.

If a model refuses a tuning parameter outright, the gateway drops that one parameter and retries the same request — up to 3 times, one knob at a time. Reasoning models do this with temperature: they accept only their own default. Only these knobs are ever dropped: temperature, top_p, top_k, frequency_penalty, presence_penalty, logit_bias, logprobs, top_logprobs, seed. messages, model and tools are never touched.

reasoning_effort says how hard a model thinks before it answers. The values are each maker's own and every model takes only its own — ask for one it does not have and this API answers 400 naming the ones it does. Thinking is billed at the output rate, like any other token a model produces. Gemini 3 levels may be written in lowercase or uppercase (low or LOW), and minimal is read as low on a model without it, as on Google's own API. On Gemini you may instead name a budget, or on Gemini 3 a level, in Google's own field, google.thinking_config.thinking_budget or thinking_level, on all three endpoints, and see the thought summary with include_thoughts: true: it comes first in the answer, inside <think>, as on Google's own API. On OpenAI's 5.6 and 6.x models max is taken too; it runs on OpenAI's Responses API, one answer per request. Claude's thinking sent to another maker's model is ignored and named in x-ignored-params. On /v1/messages Claude’s thinking comes back as thinking blocks with their signatures, as on Anthropic’s own API, and the blocks you send back reach Claude unchanged. On /v1/responses, reasoning.summary (auto, concise or detailed) returns OpenAI’s reasoning summary as a reasoning item on OpenAI’s reasoning models.

The same holds for response_format when you send audio for transcription: each model returns only its own shapes, and asking for one it does not return answers 400 naming the ones it does.

Agent tools that speak /v1/responses work here too, against every text model on the shelf — not only the ones whose maker invented that endpoint.

Claude's prompt cache is driven by the same cache_control field as Anthropic's own API — code written for Anthropic works here unchanged — and where you mark nothing, the gateway marks the system prompt and tools for you (below). It works the same way on /v1/messages, /v1/chat/completions and /v1/responses.

Automatic caching. Add "cache_control": {"type": "ephemeral"} once, at the top level of the request. The cache point goes on the last block that can hold one and moves forward as the conversation grows — the simplest choice for chats and agents.

Your own breakpoints. Put cache_control on a block: a text, picture or document part, a system block, a tool, a tool call or a tool result. Everything up to and including that block is cached — tools first, then the system prompt, then the messages. At most 4 per request, the automatic one included. Longer TTLs must come first: put every 1h mark before any 5m mark. A last-block mark with a different TTL from top-level automatic caching is rejected with 400.

If you mark nothing in the system prompt or tools, the gateway marks their ends with a 5-minute TTL, using only free slots and never more than 4 marks in total. If you request a 1-hour TTL anywhere, including at the top level, the gateway adds no marks: you manage caching yourself.

Price. Cache writes cost 1.25× the model’s input rate for 5 minutes, or 2× for one hour. Reads cost the model’s cached-input rate, the same for both TTLs. Long-context pricing scales these rates just like input pricing.

Lifetime. 5 minutes by default (or "ttl": "5m"); use "ttl": "1h" for one hour, exactly as on Anthropic. Reads renew the selected lifetime at no extra write charge.

Minimum length. A prefix shorter than the model's minimum — about one to four thousand tokens, depending on the model — is not cached: the request runs as usual, with no error and no write charge.

The cache is an exact match: change anything before a breakpoint — a tool, the system prompt, a picture, their order — and that part is written anew.

What was cached is in the answer's usage. On /v1/messages: cache_creation_input_tokens, cache_creation.ephemeral_5m_input_tokens, cache_creation.ephemeral_1h_input_tokens and cache_read_input_tokens, as Anthropic returns them. On /v1/chat/completions: prompt_tokens_details.cached_tokens (read) and prompt_tokens_details.cache_write_tokens (written), both counted inside prompt_tokens. On /v1/responses: the same two under input_tokens_details.

Other models. OpenAI and Gemini cache repeated prompts by themselves. For them, and for every model that is not Claude, cache_control is removed on the way and changes nothing.

Example

curl https://api.flintbeam.com/v1/messages \
  -H "x-api-key: sk-live-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "system": "…a long rulebook…",
    "messages": [{"role": "user", "content": "What does rule 12 say?"}]
  }'

# /v1/chat/completions, a breakpoint on one part:
# {"role": "user", "content": [
#   {"type": "text", "text": "…a long contract…", "cache_control": {"type": "ephemeral"}},
#   {"type": "text", "text": "Summarise clause 4."}]}

Each answer carries an x-request-id header, on both streamed and single-shot calls. Keep it in your logs: it is the one thing that lets us find your exact request — what it cost, which provider served it, why it failed — without guessing from timestamps.

Each key can carry its own ceilings, set in the API Keys section and enforced on every request to a model (an account can have up to 20 active keys):

• A spending ceiling — per day, week, month, or for the whole life of the key. When it is reached the key stops until the window rolls over (a 429 with Retry-After) — a lifetime ceiling stops it for good — and the balance is untouched.
• A request rate — so many requests a minute. Past it the key gets a 429 with Retry-After until the next minute.
• A list of models the key may call. Anything else is refused, and /v1/models lists only what the key may actually use.
• A list of addresses the key may be used from. A request from anywhere else is refused, even with the right key.
• Plan only. The key spends a subscription's allowance and never the balance; when the allowance is spent, the key waits for tomorrow's ration — or, on a plan with a sum of money instead of a ration, stops until the plan renews or you buy again.
• Rotating a key keeps the old one alive for a grace period, then it fails with key_expired. Revoking is immediate.

Before the call, the estimated cost is reserved from your balance; after the answer, the reservation is settled against what was really used and the difference is returned. You are charged at the price on the model’s own page — the same number the provider publishes. A request that is refused before it reaches the provider costs nothing at all.

By default, if your balance plus any bonus covering the model cannot cover the model's longest possible answer, the gateway lowers max_tokens to what they can cover. Non-streamed answers report the limit in x-ceiling-used and the reduction in x-ceiling-reduced / x-ceiling-reason: balance. Send x-fit-balance: 0 (or false) to get 402 instead when the requested limit cannot be covered. Models that answer in pictures or sound are never shortened this way. Subscription-only keys keep their plan's rules.

Text models are priced per million tokens, input and output separately; input the provider served from its cache is cheaper and listed as such on the model's page. Some speech models are priced per character and video per second, as each model's page says. The reservation is an estimate — your prompt plus max_tokens of output — and the settlement is based on the tokens the provider reports. The charge can occasionally be slightly more than the hold when a model returns more than max_tokens.

A subscription plan covers a set of models with a money allowance for the period, and on most plans a daily token ration that renews at 00:00 UTC. Plan allowances and bonus credit pay before the balance, the one that expires soonest first. When none of them can pay, your account setting decides: continue from the balance, or stop with allowance_exhausted. Models no plan covers are billed to the balance. A plan that renews is charged to your default card, and after a decline to your other saved cards in turn.

You top up by card or with crypto. Up to 5 cards can be saved, one of them the default; tick Save this card when you pay to keep the one you used. Auto top-up adds money when the balance falls below a level you choose, up to a monthly cap, at most 2 times an hour and 5 times in 24 hours, and switches itself off after 2 declined payments in a row. A receipt comes by email after each payment, and a warning when the balance falls below $10, $5 and $0.

Every request a key sends to a model — served or failed — is in the usage log with its request id, tokens and price. A request refused before it reached a provider costs nothing.

The same numbers are there for your code: GET /v1/key for what a key has spent and has left, GET /v1/credits for the balance. Neither costs anything.

Errors come back in the OpenAI shape — error.code, error.message, error.type — except on /v1/messages, which answers in Anthropic's shape. The codes worth handling:

429, and the errors caused by a spent daily volume, carry a Retry-After header whenever there is a known time to wait. Honour it; retrying sooner only gets the same answer.

Your prompts and the model's answers pass through the gateway to the provider and are never written to disk. What we keep for each request: its id, the model, token counts, latency, price, and which provider served it — enough to bill you and to debug, nothing that says what you asked. Files you upload to /v1/files are the one thing kept: until you delete them, and at most 90 days after upload.

API keys are stored only as a hash, so not even we can read them back.

Each provider processes your request under its own data policy.

• Never publish your full API key in client-side frontend code or public GitHub repositories.
• For production servers, set up an IP Whitelist in the API Keys section.
• Give each server or machine its own key. Spending limits and the model restriction are per key, so one key per place is what makes them useful — and lets you revoke one without touching the others.