Chat completions
POST /v1/chat/completions follows OpenAI’s shape. Zabio stores nothing from these calls unless your API key has body logging on (see Teams). The key needs the chat scope (keys have it by default).
For the exact shape of every request and response, with curl, Python and Node examples, see the API reference.
Request fields
Section titled “Request fields”| Field | Supported | Notes |
|---|---|---|
model |
no | a catalog id or auto, auto/best, auto/balanced, auto/cheap. Omitted means auto |
messages |
yes | 1 to 4096 messages. Roles: system, developer, user, assistant, tool. system and developer messages are joined into one system prompt. The legacy function role is refused |
messages[].content |
yes | a string, or an array of parts. user messages accept text, image_url and input_audio parts; other roles accept text parts only |
tools |
yes | up to 256 tools of type function. parameters defaults to an empty object schema |
tool_choice |
yes | auto, none, required or {"type": "function", "function": {"name": "..."}}; needs tools unless it is none |
parallel_tool_calls |
yes | passed to the vendor where supported |
max_tokens, max_completion_tokens |
yes | max_completion_tokens wins when both are present. No default: with none set, Zabio adds no output limit, as on OpenAI; providers that need a value (Anthropic, DeepSeek, Together AI) are sent the model’s maximum output (on DeepSeek and Together AI, at most the room the context window leaves beside the input). A value above the served model’s maximum output is lowered to that limit, on every attempt, so auto and failover never send a vendor a budget it rejects |
temperature |
yes | 0 to 2. Left out for a model that does not take it, and named in zabio.dropped_parameters and the x-zabio-dropped-params header; see Sampling parameters by model |
top_p |
yes | 0 to 1. Left out for a model that does not take it, and named in zabio.dropped_parameters and the x-zabio-dropped-params header; see Sampling parameters by model |
stop |
yes | a string or up to 4 strings. Where the model’s provider does not take it, Zabio cuts the answer at the first sequence itself, so it is always honored |
stream |
yes | server sent events, see below |
stream_options.include_usage |
accepted | the final usage chunk is always sent, so this flag changes nothing |
response_format |
yes | text, json_object or json_schema; see structured output below |
reasoning_effort |
yes | none, minimal, low, medium, high or xhigh, one scale for every vendor, mapped onto the served model’s own control and reported in zabio.reasoning. On auto, leave it out and Zabio chooses the setting with the model; see Reasoning levels |
user, metadata |
yes | forwarded as request metadata |
n |
only 1 | n greater than 1 is refused |
seed, logit_bias, presence_penalty, frequency_penalty |
ignored | accepted so SDK defaults do not break; listed in zabio.ignored_parameters when they carry a non default value |
modalities, audio |
yes | a spoken answer: modalities: ["text", "audio"] and audio: {"voice", "format"} on a model that answers in audio; see Audio answers |
messages[].audio |
yes | on an assistant message, {"id": ...} of an earlier spoken answer; see Audio answers |
web_search_options |
yes | the model’s own vendor searches the web before it answers, on a model named in model that takes web search (one whose zabio.pricing.per_search is set): search_context_size and user_location, with zabio.search.max_uses for the most searches (3 by default). The citations come back as url_citation entries in message.annotations, on a stream in one delta after the text. An OpenAI model always searches first; a Claude model decides. Billing, limits and what does not search are as on the Responses API |
logprobs, top_logprobs, prediction |
refused | 400 unsupported_parameter |
zabio |
yes | Zabio’s options, below |
Request bodies are limited to 32 MB (413 payload_too_large).
The zabio request object
Section titled “The zabio request object”{ "model": "auto", "messages": [...], "zabio": { "session_id": "chat-7f3a", "vendors": ["anthropic", "openai"], "fallback": "same_vendor", "cache": {"ttl": "1h", "breakpoints": "auto"}, "split": "auto", "deadline": "30m" }}| Field | Values | What it does |
|---|---|---|
session_id |
any string up to 128 characters | groups calls so the routing decision is reused and signals accumulate. See Models and routing |
vendors |
list of anthropic, openai, google |
only these vendors are candidates |
fallback |
same_vendor, cross_vendor, none |
what happens when an explicitly named model is unavailable. Default: the key’s fallback_policy |
cache.ttl |
5m, 1h, none |
prompt cache lifetime where the vendor offers one. Anthropic: 5 minutes or 1 hour (1 hour costs more to write). OpenAI, Google and the other vendors with a published cache price cache repeated prefixes on their side, so with them this value cannot be sent: a none is accepted and listed in zabio.ignored_parameters (see the per-vendor table). Caching is automatic on every call, to auto or to a named model; none turns Zabio’s markers off. Default: 5m, the lifetime used when Zabio writes. A long prompt (1,024 tokens or more) is written to the cache on its second appearance, not its first: the first time it is sent without a write, and when the same prompt or the same system prompt and tools come back within the lifetime it is written, and later calls read it. A prompt sent once never pays the write. Calls in a session_id, requests that carry earlier turns of the conversation, and requests that set cache.ttl themselves are written at once. With that default, a call in a session_id whose previous turn was more than five minutes ago gets 1h instead: a 5 minute cache would have expired and be rewritten on every turn, which costs more than no cache. zabio.cache.ttl_applied reports the choice and zabio.cache.applied who cached. Inside a batch the default is none: a batch line caches only when it asks |
cache.breakpoints |
auto, none |
auto places cache markers on the system prompt, the last tool, the last message and the previous user turn, so a conversation’s history is cached turn to turn; none places no cache markers and forces ttl to none: honored on Anthropic, reported in zabio.ignored_parameters where the vendor caches on its own (see the per-vendor table) |
split |
auto, off |
whether Zabio may split a big request under auto (see Split and route): a cheap model copies the relevant lines of a large source and the routed model answers on that excerpt, when that is cheaper. off sends the request whole. Default auto. Not a key setting: the choice lives in the request |
deadline |
a duration with units s, m or h (15m, 1h, 24h), up to 168h |
how long the answer may take. Absent or under 15 minutes: nothing changes. From 15 minutes up, the call may be served on the vendor’s flex tier where the model has one: the same model at about half the price, slower (see Flex tier). Not a guarantee of a delivery time, and not a key setting: the choice lives in the request |
search |
{"max_uses": 1 to 100} |
the most web searches the call may run when it asks for web search (web_search_options here, the web_search tool on the Responses API). 3 by default. engine may be sent as native, the only one: the model’s own vendor searches |
If your SDK rejects unknown body fields, send the same values as headers. Headers win over the body.
| Header | Same as |
|---|---|
x-zabio-session-id |
zabio.session_id |
x-zabio-cache-ttl |
zabio.cache.ttl |
x-zabio-fallback |
zabio.fallback |
x-zabio-split |
zabio.split |
x-zabio-deadline |
zabio.deadline |
Streaming
Section titled “Streaming”With stream: true the response is text/event-stream. Each event is a data: line with a chat.completion.chunk. The order is: a chunk with delta.role, content and tool call deltas, a chunk with finish_reason, then one usage chunk with empty choices, the usage block and the zabio object, then data: [DONE].
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21},"zabio":{...}}
data: [DONE]The usage chunk is always sent. If the vendor connection fails mid stream, an error object is sent in a chunk and the stream ends.
Long calls
Section titled “Long calls”Some calls take minutes: a long answer, or a model that thinks for a while before it writes. Zabio receives the answer from the model provider as a stream, also when you did not ask for one (calls on the flex tier and decision models are sent in one piece, with their own time limit), and keeps your connection alive, so nothing between you and the provider gives up first. An attempt ends only when the provider stops sending data for 2 minutes (10 minutes before the first data on those OpenAI calls), or after 30 minutes in all. Until any part of the answer has reached you, a failed attempt is tried again on another model.
- Not streamed. As soon as a model provider accepts the request (after 90 seconds at the latest), Zabio sends the
200status and headers, then one space every 15 seconds until the answer is ready; the JSON body follows the spaces, and every JSON parser skips them. On OpenAI’s models that reason, a call on your own OpenAI key, or one that setsstopon o1 or o3-mini, is answered only once the model has finished thinking, so its200goes out at the 90-second mark. A failure after that point cannot change the status any more, so the body is then only anerrorobject (message,type,code,request_id), with nochoices. Check forerrorbefore you readchoices: the OpenAI SDKs return such a body without raising. - Streamed. Whenever nothing else has been sent for 15 seconds, Zabio sends an SSE comment line (
: ZABIO PROCESSING), which SSE clients ignore. A failure after the stream started comes as an error event,data: {"error": {...}}, then a last chunk withfinish_reason: "error", thendata: [DONE]; the official SDKs raise on the error event. - Your own timeout. Stream long answers, or set your client’s request timeout to at least 30 minutes.
- If you disconnect. Closing the connection cancels the vendor call, and you pay for the work done: the input, and the output generated before you disconnected, streamed or not.
- Headers on a long call. The
200and its headers go out before the answer, so the headers that depend on it (x-zabio-vendor,x-zabio-byok,x-zabio-dropped-params) are absent then; the vendor, the model served and the routing are in the body’szabioobject, as always.
Split and route
Section titled “Split and route”Under auto, a big request can be answered in two steps when that is cheaper: a cheap model copies, word for word, the lines of your source that the question needs, and the model routing chose answers on that excerpt instead of the whole source. Zabio does this only when the last user message is plain text of several thousand tokens with a separate question that needs part of it, the request carries no tools or images, its own estimate says the split costs at most 70 percent of the unsplit call, a check confirms the excerpt holds what the question names, and every guard passes; otherwise the request goes whole, as always. The answering model is told the material was excerpted and can reply with the line NEED_MORE_SOURCE, in which case Zabio sends the full request to the same model and returns that answer. A named model is never split. Send zabio.split: "off" (or the header x-zabio-split: off) to send a request whole. Every step, model and cost is in zabio.split, and a split never costs you more than the unsplit call. See Split and route for what the model sees and Billing for the fee.
Classification jobs on auto
Section titled “Classification jobs on auto”Under auto, a request whose response_format is a json_schema made only of fixed choices (enum), booleans and bounded integers or numbers, with no tools, images or stream, may be answered by Jev (jev-1.14.0) instead of the text model routing chose: on an easy or medium classification job by the line’s rule on our measurements of Jev against the routed models, which can cost slightly more when the routed model is one our tests have not measured; on other jobs when Zabio’s estimate says Jev is cheaper. Jev answers in about 0.15 seconds with the calibrated probability of every answer; when any field of its answer is under 0.5, Zabio discards it and the text model answers as always, at Zabio’s cost. You can tell from zabio.model_served (jev-1.14.0) and zabio.decision; the answer keeps your schema’s shape. A named model is never answered by Jev. See Classification jobs on auto.
Flex tier
Section titled “Flex tier”OpenAI (flex processing) and Google (Flex inference) serve the same model at about half the price when you can wait: their own latency target is up to 15 minutes, and capacity is best effort. Zabio uses these tiers when your request says it can wait: send zabio.deadline (or the header x-zabio-deadline) with a duration of 15 minutes or more, for example "30m" or "2h". A deadline under 15 minutes, or none, changes nothing.
- Which models. OpenAI’s GPT-5, GPT-5.x and GPT-6 chat models,
o3ando4-mini; every Google Gemini model. Flex prices are half the standard input, output and cache read prices, except the cached input ofgpt-5.4ando4-mini, which OpenAI lists at 0.13 and 0.138 USD per million tokens. Every other model (the GPT-4 family,o1,o3-mini,chat-latest, every Anthropic, DeepSeek, xAI, Mistral and Together AI model) has no flex tier and is served and priced at standard, deadline or not. - With
auto. Routing compares the candidates at their flex prices where a model has one, soautocan pick a model because it is cheaper in flex. A named model is served at flex when it has a flex price. - Never a failed call. When the vendor refuses a flex request for capacity (OpenAI answers 429 resource unavailable, Google 503 or 429), Zabio retries the same model at the standard tier at once and bills the price actually used.
zabio.tier.fallbackis thencapacity. - Time. A flex attempt may take up to 900 seconds; Zabio keeps the connection alive under it as described in Long calls. Set your client’s timeout to at least 900 seconds when you send a deadline.
- What you see.
zabio.tierreportsrequested(flexorstandard, what your deadline mapped to),applied(what served the call) andfallback(capacitywhen flex was refused). - The saving. In what routing saved, a flex call is compared with your key’s baseline model at its flex price, or its standard price when that model has no flex tier, so the vendor’s own discount never counts as a saving. See Billing.
- Split and route. The pre-steps of a split (the extract and the checks) run at the standard tier; only the answer can be flex.
Work that can wait a day goes through Batches (/v1/files and /v1/batches), where every line is priced at the vendors’ batch rates, or through a background response with a deadline of 24 hours or more, which joins your organization’s next batch without a file. A synchronous call with such a deadline cannot wait that long on one connection, so it is served at the flex tier where the model has one (at standard otherwise) and zabio.tier says so: {"requested": "batch", "applied": "flex", "fallback": "synchronous"}.
Images
Section titled “Images”user messages may contain image_url parts:
{"role": "user", "content": [ {"type": "text", "text": "What is in this picture?"}, {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}]}url is either an http(s) URL or a data URI of the form data:image/<type>;base64,<data>. Zabio downloads URLs and sends the bytes to the vendor, so every vendor gets the same input. Rules for URLs:
- public hosts only; addresses in private, loopback, link local or otherwise internal ranges are refused
- at most 20 MB per image, up to 20 images per request
- the server must answer with
image/png,image/jpeg,image/webporimage/gif - at most 3 redirects,
http(s)only, 15 second timeout
Failures return 400 invalid_image_url with param pointing at the failing part. A request with images is only routed to vision capable models; a named model without vision (zabio.capabilities.vision is false in GET /v1/models) answers 400 unsupported_for_model naming the model, before anything is sent to a vendor, whatever the key’s fallback setting.
user messages may contain input_audio parts, in the shape OpenAI’s SDKs send:
{"role": "user", "content": [ {"type": "text", "text": "What is said in this clip?"}, {"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}]}data is the audio as raw base64 (not a data URL) and format is wav or mp3. The clip is sent to the model as it is, except that a WAV header written by a streaming recorder gets its two size fields set from the clip’s length; Zabio reads its header for the length and the container, and nothing is transcoded. Rules:
- the limit on a request’s audio depends on the model: Google’s Gemini models take up to 100 MB of decoded audio per request, every other model 20 MB. More than the model takes answers 413
media_too_largebefore anything is sent to a vendor, and on a named model the message states its limit.autopicks among the models that take the request’s audio - one request body is limited to 32 MB, which is about 25 MB of decoded audio, so a single request carries at most that. More reaches a Gemini model only on the Responses API, where the clips of a conversation’s stored turns are sent again with each later turn and count toward the limit
- another
formatanswers 400unsupported_value; a data URL or bytes that are not base64 answer 400invalid_value; awavthat is really anmp3, or the reverse, answers 400invalid_valueonformat - a request with audio is only routed to models that take audio input:
zabio.capabilities.audio_inputistrueon them inGET /v1/models. Today they are Google’sgemini-3.8-flash,gemini-3.6-flash,gemini-3.5-flash-lite,gemini-3-flash-previewandgemini-3.1-flash-lite, and OpenAI’sgpt-audio-1.5,gpt-audioandgpt-audio-mini(the last two until their shutdown on 2027-01-20).autopicks among the Gemini models; the OpenAI models are called by name - a named model that takes no audio answers 400
unsupported_for_modelnaming the model, before anything is sent to a vendor - for an answer in audio, see Audio answers
The vendor counts the clip in audio tokens and reports them in usage.prompt_tokens_details.audio_tokens, inside prompt_tokens; they are billed at the model’s audio price (zabio.pricing.audio_input in GET /v1/models, per million audio tokens), the text at the text price. On the Gemini models, audio the vendor read from its cache is counted in prompt_tokens_details.cached_tokens and billed at the cache price, or at the model’s cache price for audio where it has one (zabio.pricing.cache_read_audio in GET /v1/models), and audio_tokens is the rest, so no token is billed twice. A call’s details in Logs and the CSV export of your calls name that cached audio apart from the other cached tokens (tokens_cached_audio_read in the export), so you can add up what the call cost from its tokens. Google counts 25 tokens a second of audio, so a minute is about 1,500 tokens. Before the call, Zabio estimates the clip at the model’s rate for the rate limits and the balance check, from the length its header states.
On this endpoint the clip is never stored and never logged: it goes to the vendor that answers (zabio.vendor) and is dropped when the call ends. When a request to a Gemini model carries more than 20 MB of media, Google takes its clips through its own file service, and Zabio deletes them there as soon as the answer is in. With body logging on for the key, the stored request keeps the clip’s format, size and length, never its bytes. On the Responses API a stored turn keeps the clip, encrypted, under the conversation’s retention, so later turns can still hear it.
Audio answers
Section titled “Audio answers”A chat model that answers in audio speaks its answer when the request asks, in the shape OpenAI’s SDKs send:
{"model": "gpt-audio-1.5", "modalities": ["text", "audio"], "audio": {"voice": "alloy", "format": "wav"}, "messages": [{"role": "user", "content": "Tell me a short joke."}]}The answer carries the audio in choices[0].message.audio: data (the audio as base64, in the asked format), transcript (its words), and id and expires_at (see a later turn, below); content is null. Rules:
- the models that answer in audio have
zabio.capabilities.audio_outputset totrueinGET /v1/models, their formats inaudio_formats, the formats they stream inaudio_stream_formatsand their voices invoices. Today they are OpenAI’sgpt-audio-1.5,gpt-audioandgpt-audio-mini(the last two until their shutdown on 2027-01-20) and Alibaba’sqwen3.5-omni-plus,qwen3.5-omni-plus-2026-03-15andqwen3.5-omni-flash(processed outside mainland China; see Qwen Omni, below;qwen3.5-omni-flash-2026-03-15answers in text only, because it sends no audio), listed with their audio prices under Audio answers on the models page formatiswav,mp3,flac,opus,pcm16(16-bit samples with no header) oraac, as the model offers;voiceis one of the model’s voices by name (on the OpenAI models:alloy,ash,ballad,cedar,coral,echo,fable,marin,nova,onyx,sage,shimmerandverse; on the Qwen Omni models the 56 voices listed invoices, such asTinaorLiora Mira, spelled as listed). A custom voice object is refused with 400unsupported_value, as is a format or a voice the named model does not offer, with what it offers in the message- a named model that does not answer in audio answers 400
unsupported_for_model, before anything is sent to a vendor, whatever the key’s fallback setting; a fallback only ever moves the request to another model that answers in the same format and voice autodoes not answer in audio yet: an audio request toautoor one of its lines answers 400unsupported_for_model; name the modelmodalitiesmust be["text", "audio"]: audio alone answers 400invalid_value, as the models refuse it- a spoken answer cannot run in a batch, and the Responses API answers in text (400
unsupported_parameteronmodalitiesoraudio)
Streaming. The OpenAI models stream an answer in pcm16 only: stream: true with another format answers 400 unsupported_value on audio.format, before anything is sent to a vendor; without stream every format works. With stream: true the audio arrives in choices[0].delta.audio chunks, in OpenAI’s shape: pieces of data and of transcript, the id, and last a chunk with expires_at alone. Decode each data piece from base64 and join the bytes in order; pcm16 can be played as it arrives.
Qwen Omni. The Qwen Omni models answer in audio only when the request streams (zabio.capabilities.audio_stream_only in GET /v1/models): without stream: true, a request with the audio modality answers 400 unsupported_value on stream, before anything is sent to a vendor, because the vendor would answer in text and still bill the audio. A request without the audio modality is served streamed or not. They answer in pcm16 only (24 kHz, 16-bit, mono). The words of the answer arrive in content (in delta.content when streamed), not in transcript. They take text in, not images, audio, video or tools, and an earlier answer’s audio id is refused: send the earlier answer’s content as the assistant’s content.
A later turn. To go on after a spoken answer, send the assistant turn back as {"role": "assistant", "audio": {"id": "<the answer's audio.id>"}}. The vendor keeps that audio until expires_at, and Zabio keeps none, so such a request must name a model of the vendor that gave the answer (to auto, or to another vendor’s model, it answers 400 unsupported_for_model), and after expires_at the vendor refuses the id. Sending the transcript as the assistant’s content instead works with any model.
Billing. The vendor reports the answer’s audio in usage.completion_tokens_details.audio_tokens and its text in text_tokens, both inside completion_tokens. The audio tokens are billed at the model’s audio output price (zabio.pricing.audio_output in GET /v1/models, per million audio tokens), the text at its output price, plus the fee as on every call; if a vendor reports no audio count, the whole output is billed at the audio price, and audio tokens a vendor reports for an answer that carried no audio are not billed. On the Qwen Omni models the text of an answer that carries audio is free and only its audio is billed, as Alibaba bills it (zabio.pricing.text_free_with_audio in GET /v1/models); an answer in text alone pays the output price. Before the call the balance check counts the whole output budget at the audio price: your max_tokens, or at least 2,048 tokens when you send none; when your balance cannot pay for the model’s whole output, the model is sent the output the balance can pay for. A stream that ends without its usage is billed from what reached you, marked estimated.
Never stored. The spoken answer goes from the vendor to you; Zabio does not keep the audio, not in a file and not in a log. With body logging on for the key, the stored answer keeps its transcript, its id and its size in bytes, never the audio.
user messages may contain video_url parts, the image part’s shape with a file form beside it:
{"role": "user", "content": [ {"type": "text", "text": "What happens in this video?"}, {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}]}video_url.url is one of three things: a data URL (data:video/mp4;base64,..., also video/quicktime and video/webm), an https URL, or a public YouTube URL (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). Instead of a url, video_url.file_id can name a file you uploaded to POST /v1/files with purpose user_data; the key must be able to read it. Videos are MP4, MOV or WebM; Zabio reads the file’s header for its format and length and changes nothing in it. Rules:
- an https URL is downloaded by Zabio under the rules for image URLs: public addresses only, 15 seconds, at most 20 MB. For a bigger video, upload it and send its
file_id, or send its URL to a Qwen model by name (the next rule) - an https video over 20 MB sent to a Qwen model by name is not downloaded by Zabio: Alibaba fetches it from your URL, up to the 2 GB Alibaba states as its limit. The URL must be reachable from the public internet, and Alibaba asks that its server state the file’s size and type (
Content-LengthandContent-Type). Zabio reads only the first 1 MB of the file, under the same rules as any download, for its format and length. An MP4 or MOV saved for streaming (its index at the start of the file, often called fast start) states its length there. One with the index at the end does not, and is estimated at ten minutes. Every other model answers 400invalid_video_urlfor an https video over 20 MB, and so doesauto, which does not pick the Qwen models - at most 10 videos per request, and at most 100 MB of video in all (413
media_too_large). A data URL also counts toward the 32 MB request body, so a video over about 24 MB goes as a file - a request with video is only routed to models that take video:
zabio.capabilities.video_inputistrueon them inGET /v1/models. Today they are Google’sgemini-3.8-flash,gemini-3.6-flash,gemini-3.5-flash-lite,gemini-3-flash-previewandgemini-3.1-flash-lite, and Alibaba’sqwen3.8-omni-flash,qwen3.8-flashandqwen3.7-plus(alsoqwen3.7-plus@alibaba-us), and its Qwen 3.6 and 3.5 modelsqwen3.6-plus,qwen3.6-flash,qwen3.6-35b-a3b,qwen3.6-27b,qwen3.5-plus-2026-04-20,qwen3.5-plus-2026-02-15,qwen3.5-flash-2026-02-23,qwen3.5-397b-a17b,qwen3.5-122b-a10b,qwen3.5-35b-a3bandqwen3.5-27b.autopicks among the Gemini models; the Qwen models are called by name - a named model that takes no video answers 400
unsupported_for_modelnaming the model, before anything is sent to a vendor - YouTube URLs and WebM videos go to the Gemini models only. The Qwen models take a video sent as data only under 10 MB of base64 (about 7.5 MB of video); a bigger video goes to them as an https URL, which Zabio passes on for the vendor to fetch. A named Qwen model asked otherwise answers 400
unsupported_valuesaying why - a video cannot run in a batch or as a background Response: Zabio does not keep videos until later
The vendor counts the video in input tokens, inside usage.prompt_tokens, and they are billed at the model’s input price; A test clip counted about 65 tokens a second on Gemini without sound and about 90 with it, and on the Qwen models one token for every 32 by 32 pixels of a frame, one frame a second: about 220 a second at 360p, about 400 at 480p and about 600 at 720p and above, so a minute on Gemini is about 4,000 to 6,000 tokens; Google’s page states about 100 a second at low resolution and 300 at high. Gemini counts a video’s sound inside the video’s tokens, at the input price. Alibaba’s Omni model counts a video’s sound apart, in usage.prompt_tokens_details.audio_tokens, billed at the model’s audio price. The other Qwen models do not listen to a video’s sound and count none. Before the call, Zabio estimates the video at the model’s rate for the rate limits and the balance check, from the length its header states; a video whose length Zabio cannot read (a YouTube URL, a WebM recorded live, an https video over 20 MB whose length is not at the start of the file) is estimated at ten minutes. A call whose stream ends before the vendor reports its usage is billed from Zabio’s own count: the length Zabio read, at no more than 220 tokens a second on the Qwen models, or 594 when Zabio read a picture of 720p or larger from the file’s start.
Zabio never keeps a video: it goes to the vendor that answers (zabio.vendor) and is dropped when the call ends. Google takes a video over 20 MB through its own file service, and Zabio deletes it there as soon as the answer is in. An https video over 20 MB sent to a Qwen model is fetched by Alibaba from your URL; Zabio reads its first 1 MB and keeps none of it. Nothing of the video is logged; with body logging on for the key, the stored request keeps the video’s format, size and length, never the video or its address. On the Responses API a stored turn keeps the same reference only, so a later turn of the conversation does not see the video again.
Function tools work as in OpenAI. Send tools, receive tool_calls on the assistant message with finish_reason: "tool_calls", answer with tool messages carrying tool_call_id. Arguments are always a JSON string ({} when empty). Requests with tools are only routed to tool capable models.
Tools on Gemini models
Section titled “Tools on Gemini models”Google’s Gemini models take a subset of JSON Schema in a tool’s parameters. Zabio converts each schema on the way to a Gemini model, so the schemas the OpenAI and Anthropic SDKs and Claude Code send work unchanged: references ($ref to $defs) are written out in place, a list of types becomes one type marked nullable, const becomes a one value enum, oneOf becomes anyOf, and an integer’s exclusiveMinimum or exclusiveMaximum becomes the next whole number’s minimum or maximum. Keywords with no Gemini equivalent are left out of the call, and the ones that carried a rule are listed in zabio.ignored_parameters as tools.parameters.<keyword>, once each: for example tools.parameters.additionalProperties, so the model may add a property your schema closed. A format Gemini does not know, an enum of numbers, multipleOf, uniqueItems and a bound on a decimal number are repeated in the field’s description, so the model still reads them. Annotations such as $schema, $id and $comment are left out without a mention. A tool that takes no parameters is declared without any.
A schema that refers to itself (a recursive $ref, such as a tree whose children are trees) cannot be written out for Gemini. Under auto the Gemini models are left out for that request and another model answers; a request that names a Gemini model gets 400 unsupported_parameter naming the tool and the keyword, and on that 400 nothing is sent to Google and nothing is billed.
Structured output
Section titled “Structured output”response_format.type |
Behaviour |
|---|---|
text |
default |
json_object |
OpenAI, Google, DeepSeek, xAI, Mistral AI and Together AI use their native JSON mode. Anthropic has no JSON object mode: Zabio adds a system instruction asking for exactly one JSON object and nothing else, starts the reply inside the object on models that allow it, and strips a Markdown code fence around the object when the model adds one anyway. This is best effort by construction. Validate the output on your side when the answer may come from an Anthropic model, and prefer json_schema whenever you know the shape you want |
json_schema |
{"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}. Mapped to each vendor’s native structured output. schema is required. Only routed to models with json_schema support (not the DeepSeek direct models, nor the Qwen models on Alibaba Cloud that do not enforce a schema; zabio.capabilities.json_schema in GET /v1/models says which models take it). On Jev, the decision model (jev-1.14.0 or jev-1.13.0), the schema’s properties are the questions Jev answers, each with its probability in zabio.decision; see Decision models |
The response
Section titled “The response”A standard chat.completion object. usage.prompt_tokens counts every input token, cached or not, so totals match what the vendor processed; usage.prompt_tokens_details.cached_tokens is the cached part, and usage.completion_tokens_details.reasoning_tokens is the vendor’s count of thinking tokens inside completion_tokens, present when the vendor reports one. finish_reason is stop, length, tool_calls or content_filter. Zabio serves exactly one choice. A reasoning model that spends its whole output budget thinking returns an empty answer with finish_reason: "length": raise max_tokens so it leaves room for the answer above the thinking, or lower reasoning_effort.
The zabio response object
Section titled “The zabio response object”| Field | Type | Meaning |
|---|---|---|
vendor |
string | who served the call: anthropic, openai, google, deepseek, xai, mistral, together or typesafe |
model_served |
string | the model that answered; differs from model you sent for auto and fallbacks |
routing |
object or absent | line, task, task_type (the kind of work as a tag, see Kinds of work), difficulty, band, stakes, biased, cell, confidence (0 to 1), reason (the classifier’s sentence), trigger (why the decision was made; see Models and routing), classifier (who decided: typesafe/jev-1.13.0, or the text classifier it fell back to; absent on explicit models), effort (the reasoning setting chosen with the model), effort_reason (why) and sticky (present only when the session’s warm prompt cache decided the pick: the model kept and the one cold pricing would have chosen). Absent on explicit models without routing information |
reasoning |
object | requested (the level you sent, omitted when none) and applied (what the served model got: default, off, the vendor’s level name, budget N, on, always on or not supported) |
cost_micros |
integer | what you were billed, in millionths of a US dollar (1,000,000 micros = 1 USD) |
cost |
object | the breakdown: vendor_micros (provider list price), service_fee_micros, call_fee_micros (the fixed fee an auto request pays once, the price of automatic model choice; 0 on a named model), savings_fee_micros and classifier_micros (both always 0, kept so existing clients keep parsing them). The cost only: what routing saved is computed for a period, never per call (see The saving of a period) |
byok |
boolean | true when the call used your own vendor key |
cache |
object | read_tokens, write_tokens, ttl_applied (5m, 1h or none) and applied (none, zabio or vendor_automatic: who cached, see the per-vendor table) |
session_id |
string | echoes the session id you sent |
escalated_from |
string | the line Zabio applied (cheap, balanced or best, also on plain auto) and the model whose answer auto replaced: on the Responses API when that model asked for a stronger one, and on any request that is not streamed when its answer failed Zabio’s check |
compacted |
boolean | Responses API only: the stored history was summarized before this turn |
vendor_stop_reason |
string | the vendor’s own stop reason, for debugging |
ignored_parameters |
list | request fields Zabio accepted and ignored |
dropped_parameters |
list | sampling parameters the model that answered does not take (temperature, top_p), left out of its request; also the x-zabio-dropped-params header |
attempts |
integer | how many providers were tried before one answered |
decision |
object | when Jev answered (jev-1.14.0 or jev-1.13.0), named or chosen by auto for a classification job: the calibrated probabilities behind each property of the answer, see Decision models |
no_answer |
string | present when the request ended with no answer, the output budget spent on reasoning, or the input left no room for an answer in the model’s context window: what happened, what to change and whether it was billed (not, within the limits in Checked answers) |
split |
object | present while split and route is on: applied (true when the answer came from an excerpt of your source), pattern (distill), reason (why the request was not split: named_model, opt_out, not_eligible, below_threshold, jev_no, jev_failed, price_check), steps (every call of the split: role questions, extract, check or answer, with vendor, model, input_tokens, output_tokens, micros at list price and billed), excerpt (lines_kept, lines_total, tokens, verbatim_rate), check_p (the check’s probability), and fallback (the guard that sent the request whole). See Split and route |
tier |
object | the service tier: requested (standard, flex or batch, what your deadline mapped to: flex from 15 minutes, batch from 24 hours), applied (what served the call) and fallback (capacity when flex was requested and the vendor refused it, so standard served and was billed; synchronous when the deadline asked for batch on a synchronous call, which cannot wait a day, so flex or standard served). See Flex tier |
search |
object | present on a call that could search the web: form (native: the model’s own vendor searched), mode (tool), engine (the vendor), searches (the searches the vendor counted), max_uses (the most the call could run) and cost_micros (the search line of the bill, inside cost_micros above; cost.search_micros and cost.search_fee_micros are its parts). See Web search |
plan |
object | present on a call served under the Free limits (see Billing): tier (free), reason (free_plan, the organization never topped up; zero_balance, a paid organization at zero continuing on the free tier), paid_would_use (on auto, the model a paid account would have been given, when it differs from the one that answered) and topup_url. Absent on a paid call. Not to be confused with tier, the vendor processing tier |
Fields with empty values are omitted, so check for presence.
Response headers
Section titled “Response headers”| Header | Meaning |
|---|---|
x-request-id |
id to quote in support requests |
x-zabio-vendor |
same as zabio.vendor. On a call whose 200 went out before the answer (see Long calls) it is absent, so read vendor, model and routing from the body’s zabio object |
x-zabio-byok |
true when your own vendor key was used |
x-zabio-searches |
the web searches the vendor counted on the call; only on a response that is not streamed and asked for web search |
x-zabio-balance-micros |
your organization’s credit balance after the admission check |
x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests |
the key’s requests per minute bucket |
x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-tokens |
the key’s tokens per minute bucket. It is charged up front with the input estimate plus the output budget, clamped to what the served model can produce, and settled after the call; a max_tokens far above what the job needs can hit the limit early, so set it near what you need |
x-zabio-quota-scope, x-zabio-quota-limit, x-zabio-quota-remaining |
present when a spend limit applies to the key (key, over its reset period) or the monthly quota of the member who created it (member) |
x-zabio-plan |
free on every call served under the Free limits; absent on a paid call |
x-ratelimit-limit-requests-day, x-ratelimit-remaining-requests-day, x-ratelimit-reset-requests-day |
the Free plan’s day: 100 successful requests, what is left, and the time to 00:00 UTC. Only with x-zabio-plan: free; on such calls x-ratelimit-*-requests is the Free minute bucket (20), which is tighter than the key’s own |
x-zabio-free-limit |
on a 429 or 403 free_tier_limit, which limit was met: requests_per_day, requests_per_minute, daily_cost, input_tokens, max_tokens, members or api_keys |
Retry-After |
seconds to wait, on 429 and on retryable 5xx |
Server-Timing |
the time each stage of the request took; see Server timing below |
See Errors for what happens when a limit is hit.
Server timing
Section titled “Server timing”Answers from /v1 carry the standard Server-Timing header: the time Zabio spent in each stage of your request, in milliseconds. A request refused at the API key check has none.
Server-Timing: auth;dur=0.9, admission;dur=2.4, routing;dur=88.1, vendor_first_byte;dur=412.6, vendor_rest;dur=1203.3, after_vendor;dur=14.8| Entry | What it measures |
|---|---|
auth |
checking your API key |
admission |
the balance, rate limit, spend limit and Free plan checks |
routing |
choosing the model: on auto, classifying the job and selecting the model; on a named model, the selection alone |
vendor_first_byte |
from Zabio’s first request to a model provider to the first byte of the answer you got, including any failed attempt on another model before it |
vendor_rest |
from that first byte to the provider’s last byte |
after_vendor |
from the provider’s last byte to the headers: what Zabio did before it answered |
The header goes out with the status, so it holds the stages finished by then. A streamed answer’s headers leave as the answer starts, so its header ends at vendor_first_byte; so does a call whose 200 went out before the answer (see Long calls). A stage the request never reached, because it was refused before it, is absent. The time between stages, such as reading your request body, is in no entry, so the entries add up to less than the whole call. The header holds durations only, nothing about your organization or your request. Entries with other names may be added by the network between you and Zabio; ignore them.
With the OpenAI Python SDK, read it from the raw response:
raw = client.chat.completions.with_raw_response.create( model="auto", messages=[{"role": "user", "content": "Hello"}],)print(raw.headers.get("server-timing"))completion = raw.parse()