Skip to content
Zabio is in beta: models, prices and features can change. Tell us what breaks at hello@zabio.ai.

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.

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).

{
"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

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.

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 200 status 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 sets stop on o1 or o3-mini, is answered only once the model has finished thinking, so its 200 goes out at the 90-second mark. A failure after that point cannot change the status any more, so the body is then only an error object (message, type, code, request_id), with no choices. Check for error before you read choices: 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 with finish_reason: "error", then data: [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 200 and 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’s zabio object, as always.

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.

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.

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, o3 and o4-mini; every Google Gemini model. Flex prices are half the standard input, output and cache read prices, except the cached input of gpt-5.4 and o4-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, so auto can 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.fallback is then capacity.
  • 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.tier reports requested (flex or standard, what your deadline mapped to), applied (what served the call) and fallback (capacity when 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"}.

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/webp or image/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_large before anything is sent to a vendor, and on a named model the message states its limit. auto picks 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 format answers 400 unsupported_value; a data URL or bytes that are not base64 answer 400 invalid_value; a wav that is really an mp3, or the reverse, answers 400 invalid_value on format
  • a request with audio is only routed to models that take audio input: zabio.capabilities.audio_input is true on them in GET /v1/models. Today they are Google’s gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3-flash-preview and gemini-3.1-flash-lite, and OpenAI’s gpt-audio-1.5, gpt-audio and gpt-audio-mini (the last two until their shutdown on 2027-01-20). auto picks among the Gemini models; the OpenAI models are called by name
  • a named model that takes no audio answers 400 unsupported_for_model naming 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.

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_output set to true in GET /v1/models, their formats in audio_formats, the formats they stream in audio_stream_formats and their voices in voices. Today they are OpenAI’s gpt-audio-1.5, gpt-audio and gpt-audio-mini (the last two until their shutdown on 2027-01-20) and Alibaba’s qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15 and qwen3.5-omni-flash (processed outside mainland China; see Qwen Omni, below; qwen3.5-omni-flash-2026-03-15 answers in text only, because it sends no audio), listed with their audio prices under Audio answers on the models page
  • format is wav, mp3, flac, opus, pcm16 (16-bit samples with no header) or aac, as the model offers; voice is one of the model’s voices by name (on the OpenAI models: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer and verse; on the Qwen Omni models the 56 voices listed in voices, such as Tina or Liora Mira, spelled as listed). A custom voice object is refused with 400 unsupported_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
  • auto does not answer in audio yet: an audio request to auto or one of its lines answers 400 unsupported_for_model; name the model
  • modalities must be ["text", "audio"]: audio alone answers 400 invalid_value, as the models refuse it
  • a spoken answer cannot run in a batch, and the Responses API answers in text (400 unsupported_parameter on modalities or audio)

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-Length and Content-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 400 invalid_video_url for an https video over 20 MB, and so does auto, 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_input is true on them in GET /v1/models. Today they are Google’s gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3-flash-preview and gemini-3.1-flash-lite, and Alibaba’s qwen3.8-omni-flash, qwen3.8-flash and qwen3.7-plus (also qwen3.7-plus@alibaba-us), and its Qwen 3.6 and 3.5 models qwen3.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-a3b and qwen3.5-27b. auto picks among the Gemini models; the Qwen models are called by name
  • a named model that takes no video answers 400 unsupported_for_model naming 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_value saying 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.

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.

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

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.

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.

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.

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()