Chat completions
POST /v1/chat/completions sigue el formato de OpenAI. Zabio no guarda nada de estas llamadas salvo que tu API key tenga activado el registro de cuerpos (consulta Organizaciones y equipos). La key necesita el scope chat (las keys lo tienen por defecto).
Para la forma exacta de cada petición y respuesta, con ejemplos en curl, Python y Node, consulta la Referencia de la API.
Campos de la petición
Section titled “Campos de la petición”| Campo | Soporte | Notas |
|---|---|---|
model |
no | un id del catálogo o auto, auto/best, auto/balanced, auto/cheap. Si se omite, es auto |
messages |
sí | de 1 a 4096 mensajes. Roles: system, developer, user, assistant, tool. Los mensajes system y developer se unen en un solo system prompt. El rol antiguo function se rechaza |
messages[].content |
sí | una cadena o un array de partes. Los mensajes user aceptan partes text, image_url e input_audio; el resto de roles solo partes text |
tools |
sí | hasta 256 herramientas de tipo function. parameters toma por defecto un esquema de objeto vacío |
tool_choice |
sí | auto, none, required o {"type": "function", "function": {"name": "..."}}; requiere tools salvo que sea none |
parallel_tool_calls |
sí | se pasa al proveedor cuando lo soporta |
max_tokens, max_completion_tokens |
sí | max_completion_tokens gana cuando están los dos. Sin valor por defecto: si no lo fijas, Zabio no añade ningún límite de salida, como OpenAI; a los proveedores que necesitan un valor (Anthropic, DeepSeek, Together AI) se les envía la salida máxima del modelo (en DeepSeek y Together AI, como mucho el espacio que la ventana de contexto deja junto a la entrada). Un valor por encima de la salida máxima del modelo servido se baja a ese límite, en cada intento, para que auto y el fallback nunca envíen al proveedor un presupuesto que rechace |
temperature |
sí | de 0 a 2. Se omite para un modelo que no lo admite, y se nombra en zabio.dropped_parameters y en la cabecera x-zabio-dropped-params; consulta Parámetros de muestreo por modelo |
top_p |
sí | de 0 a 1. Se omite para un modelo que no lo admite, y se nombra en zabio.dropped_parameters y en la cabecera x-zabio-dropped-params; consulta Parámetros de muestreo por modelo |
stop |
sí | una cadena o hasta 4 cadenas. Donde el proveedor del modelo no lo admite, Zabio corta la respuesta en la primera secuencia, así que siempre se respeta |
stream |
sí | server sent events, ver más abajo |
stream_options.include_usage |
se acepta | el chunk final de uso se envía siempre, así que este flag no cambia nada |
response_format |
sí | text, json_object o json_schema; ver salida estructurada más abajo |
reasoning_effort |
sí | none, minimal, low, medium, high o xhigh, una sola escala para todos los proveedores, aplicada al control propio del modelo servido e indicada en zabio.reasoning. Con auto, no lo envíes y Zabio elige el ajuste junto con el modelo; consulta Niveles de razonamiento |
user, metadata |
sí | se reenvían como metadatos de la petición |
n |
solo 1 | n mayor que 1 se rechaza |
seed, logit_bias, presence_penalty, frequency_penalty |
se ignoran | se aceptan para que los valores por defecto de los SDK no fallen; aparecen en zabio.ignored_parameters cuando llevan un valor distinto del predeterminado |
modalities, audio |
sí | una respuesta en audio: modalities: ["text", "audio"] y audio: {"voice", "format"} en un modelo que responde en audio; ver Respuestas en audio |
messages[].audio |
sí | en un mensaje assistant, {"id": ...} de una respuesta en audio anterior; ver Respuestas en audio |
web_search_options |
sí | el propio proveedor del modelo busca en la web antes de responder, en un modelo nombrado en model que acepta búsqueda web (uno cuyo zabio.pricing.per_search aparece): search_context_size y user_location, con zabio.search.max_uses para el máximo de búsquedas (3 por defecto). Las citas vuelven como entradas url_citation en message.annotations, en streaming en un solo delta después del texto. Un modelo de OpenAI siempre busca primero; un modelo Claude decide. La facturación, los límites y lo que no busca son como en la Responses API |
logprobs, top_logprobs, prediction |
se rechazan | 400 unsupported_parameter |
zabio |
sí | las opciones de Zabio, más abajo |
Los cuerpos de petición están limitados a 32 MB (413 payload_too_large).
El objeto zabio de la petición
Section titled “El objeto zabio de la petición”{ "model": "auto", "messages": [...], "zabio": { "session_id": "chat-7f3a", "vendors": ["anthropic", "openai"], "fallback": "same_vendor", "cache": {"ttl": "1h", "breakpoints": "auto"}, "split": "auto", "deadline": "30m" }}| Campo | Valores | Qué hace |
|---|---|---|
session_id |
cualquier cadena de hasta 128 caracteres | agrupa llamadas para reutilizar la decisión de enrutado y acumular señales. Consulta Modelos y enrutado |
vendors |
lista con anthropic, openai, google |
solo estos proveedores son candidatos |
fallback |
same_vendor, cross_vendor, none |
qué pasa cuando un modelo nombrado explícitamente no está disponible. Por defecto: el fallback_policy de la key |
cache.ttl |
5m, 1h, none |
duración de la caché de prompt cuando el proveedor la ofrece. Anthropic: 5 minutos o 1 hora (la de 1 hora cuesta más escribirla). OpenAI, Google y los demás proveedores con un precio de caché publicado guardan los prefijos repetidos en caché por su cuenta, así que con ellos este valor no se puede enviar: un none se acepta y se lista en zabio.ignored_parameters (consulta la tabla por proveedor). La caché es automática en cada llamada, a auto o a un modelo nombrado; none apaga los marcadores de Zabio. Por defecto: 5m, la duración que se usa cuando Zabio escribe. Un prompt largo (1,024 tokens o más) se escribe en la caché en su segunda aparición, no en la primera: la primera vez se envía sin escritura, y cuando el mismo prompt, o el mismo system prompt con las mismas herramientas, vuelve dentro de la vida de la caché, se escribe y las llamadas siguientes lo leen. Un prompt enviado una sola vez nunca paga la escritura. Las llamadas de una session_id, las peticiones que llevan turnos anteriores de la conversación y las peticiones que fijan cache.ttl se escriben enseguida. Con ese valor por defecto, una llamada de una session_id cuyo turno anterior fue hace más de cinco minutos recibe 1h: una caché de 5 minutos habría caducado y se reescribiría en cada turno, lo que cuesta más que no usar caché. zabio.cache.ttl_applied informa de la elección y zabio.cache.applied de quién guardó en caché. Dentro de un lote el valor por defecto es none: una línea de lote solo usa caché cuando lo pide |
cache.breakpoints |
auto, none |
auto coloca marcadores de caché en el system prompt, en la última herramienta, en el último mensaje y en el turno anterior del usuario, de modo que el historial de una conversación se guarda en caché de un turno al siguiente; none no coloca marcadores de caché y fuerza ttl a none: se respeta en Anthropic y se informa en zabio.ignored_parameters donde el proveedor guarda en caché por su cuenta (consulta la tabla por proveedor) |
split |
auto, off |
si Zabio puede dividir una petición grande con auto (ver División y enrutado): un modelo barato copia las líneas relevantes de una fuente grande y el modelo enrutado responde sobre ese extracto, cuando sale más barato. off envía la petición entera. Por defecto auto. No es un ajuste de la key: la elección va en la petición |
deadline |
una duración con unidades s, m o h (15m, 1h, 24h), hasta 168h |
cuánto puede tardar la respuesta. Sin valor o por debajo de 15 minutos, no cambia nada. A partir de 15 minutos, la llamada puede servirse en el nivel flex del proveedor cuando el modelo lo tiene: el mismo modelo a la mitad de precio, más despacio (ver Nivel flex). No garantiza un plazo de entrega, y no es un ajuste de la key: la elección va en la petición |
search |
{"max_uses": de 1 a 100} |
el máximo de búsquedas web que la llamada puede hacer cuando pide búsqueda web (web_search_options aquí, la herramienta web_search en la Responses API). 3 por defecto. engine puede enviarse como native, el único: busca el propio proveedor del modelo |
Si tu SDK rechaza campos desconocidos en el cuerpo, envía los mismos valores como cabeceras. Las cabeceras tienen prioridad sobre el cuerpo.
| Cabecera | Equivale a |
|---|---|
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”Con stream: true la respuesta es text/event-stream. Cada evento es una línea data: con un chat.completion.chunk. El orden es: un chunk con delta.role, los deltas de contenido y de llamadas a herramientas, un chunk con finish_reason, después un chunk de uso con choices vacío, el bloque usage y el objeto zabio, y por último 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":"Hola"},"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]El chunk de uso se envía siempre. Si la conexión con el proveedor falla a mitad del stream, se envía un objeto error en un chunk y el stream termina.
Llamadas largas
Section titled “Llamadas largas”Algunas llamadas tardan minutos: una respuesta larga, o un modelo que piensa un rato antes de escribir. Zabio recibe la respuesta del proveedor del modelo en streaming, también cuando no lo pediste (las llamadas del nivel flex y los modelos de decisión se envían en una sola pieza, con su propio límite de tiempo), y mantiene viva tu conexión, para que nada entre tú y el proveedor se rinda antes. Un intento solo termina cuando el proveedor deja de enviar datos durante 2 minutos (10 minutos antes de los primeros datos en esas llamadas a OpenAI), o tras 30 minutos en total. Mientras ninguna parte de la respuesta te haya llegado, un intento fallido se repite con otro modelo.
- Sin streaming. En cuanto un proveedor acepta la petición (a los 90 segundos como muy tarde), Zabio envía el estado
200y las cabeceras, y después un espacio cada 15 segundos hasta que la respuesta está lista; el cuerpo JSON sigue a los espacios, y todo analizador JSON los ignora. En los modelos de OpenAI que razonan, una llamada con tu propia key de OpenAI, o una que fijastopen o1 u o3-mini, solo se responde cuando el modelo ha terminado de pensar, así que su200sale a los 90 segundos. Un fallo después de ese momento ya no puede cambiar el estado, así que el cuerpo es entonces solo un objetoerror(message,type,code,request_id), sinchoices. Comprueba si hayerrorantes de leerchoices: los SDK de OpenAI devuelven ese cuerpo sin lanzar una excepción. - Con streaming. Siempre que no se ha enviado nada durante 15 segundos, Zabio envía una línea de comentario SSE (
: ZABIO PROCESSING), que los clientes SSE ignoran. Un fallo después de empezar el stream llega como un evento de error,data: {"error": {...}}, después un último chunk confinish_reason: "error", y despuésdata: [DONE]; los SDK oficiales lanzan una excepción con el evento de error. - Tu propio timeout. Pide las respuestas largas en streaming, o pon el timeout de petición de tu cliente en al menos 30 minutos.
- Si te desconectas. Cerrar la conexión cancela la llamada al proveedor, y pagas el trabajo hecho: la entrada y la salida generada antes de desconectarte, con o sin streaming.
- Cabeceras en una llamada larga. El
200y sus cabeceras salen antes de la respuesta, así que las cabeceras que dependen de ella (x-zabio-vendor,x-zabio-byok,x-zabio-dropped-params) no aparecen entonces; el proveedor, el modelo servido y el enrutado están en el objetozabiodel cuerpo, como siempre.
División y enrutado
Section titled “División y enrutado”Con auto, una petición grande puede responderse en dos pasos cuando sale más barato: un modelo barato copia, palabra por palabra, las líneas de tu fuente que la pregunta necesita, y el modelo que eligió el enrutado responde sobre ese extracto en lugar de sobre la fuente entera. Zabio lo hace solo cuando el último mensaje del usuario es texto plano de varios miles de tokens con una pregunta aparte que necesita una parte de él, la petición no lleva herramientas ni imágenes, su propia estimación dice que la división cuesta como máximo el 70 por ciento de la llamada entera, una comprobación confirma que el extracto contiene lo que la pregunta nombra y todas las salvaguardas pasan; si no, la petición va entera, como siempre. Al modelo que responde se le dice que el material se extractó y puede contestar con la línea NEED_MORE_SOURCE; en ese caso Zabio envía la petición completa al mismo modelo y devuelve esa respuesta. Un modelo con nombre nunca se divide. Envía zabio.split: "off" (o la cabecera x-zabio-split: off) para mandar una petición entera. Cada paso, modelo y coste está en zabio.split, y una división nunca te cuesta más que la llamada entera. Consulta División y enrutado para saber qué ve el modelo y Facturación para la comisión.
Tareas de clasificación en auto
Section titled “Tareas de clasificación en auto”Con auto, una petición cuyo response_format es un json_schema formado solo por opciones fijas (enum), booleanos y enteros o números acotados, sin herramientas, imágenes ni stream, puede responderla Jev (jev-1.14.0) en lugar del modelo de texto que eligió el enrutado: en una tarea de clasificación fácil o media, según la regla de la línea sobre nuestras mediciones de Jev frente a los modelos enrutados, lo que puede costar un poco más cuando el modelo enrutado es uno que nuestras pruebas no han medido; en las demás tareas, cuando la estimación de Zabio dice que Jev es más barato. Jev responde en unos 0.15 segundos con la probabilidad calibrada de cada respuesta; cuando algún campo de su respuesta está por debajo de 0.5, Zabio la descarta y responde el modelo de texto como siempre, a coste de Zabio. Lo sabes por zabio.model_served (jev-1.14.0) y zabio.decision; la respuesta conserva la forma de tu esquema. Un modelo con nombre nunca lo responde Jev. Ver Tareas de clasificación en auto.
Nivel flex
Section titled “Nivel flex”OpenAI (flex processing) y Google (Flex inference) sirven el mismo modelo a la mitad de precio, más o menos, cuando puedes esperar: su propio objetivo de latencia llega a 15 minutos, y la capacidad es la que haya en cada momento. Zabio usa estos niveles cuando tu petición dice que puede esperar: envía zabio.deadline (o la cabecera x-zabio-deadline) con una duración de 15 minutos o más, por ejemplo "30m" o "2h". Un plazo menor de 15 minutos, o ninguno, no cambia nada.
- Qué modelos. Los modelos de chat GPT-5, GPT-5.x y GPT-6 de OpenAI,
o3yo4-mini; todos los modelos Gemini de Google. Los precios flex son la mitad de los precios estándar de entrada, salida y lectura de caché, salvo la entrada en caché degpt-5.4y deo4-mini, que OpenAI publica a 0.13 y 0.138 USD por millón de tokens. Los demás modelos (la familia GPT-4,o1,o3-mini,chat-latesty todos los de Anthropic, DeepSeek, xAI, Mistral y Together AI) no tienen nivel flex y se sirven y facturan a precio estándar, con plazo o sin él. - Con
auto. El enrutado compara los candidatos a su precio flex cuando el modelo lo tiene, así queautopuede elegir un modelo porque sale más barato en flex. Un modelo con nombre se sirve en flex cuando tiene precio flex. - Nunca una llamada fallida. Cuando el proveedor rechaza una petición flex por falta de capacidad (OpenAI responde 429 resource unavailable, Google 503 o 429), Zabio reintenta al momento el mismo modelo en el nivel estándar y factura el precio que se usó de verdad.
zabio.tier.fallbackes entoncescapacity. - Tiempo. Un intento flex puede tardar hasta 900 segundos; Zabio mantiene la conexión viva mientras tanto, como se explica en Llamadas largas. Pon el timeout de tu cliente en al menos 900 segundos cuando envíes un plazo.
- Qué ves.
zabio.tierindicarequested(flexostandard, a qué se tradujo tu plazo),applied(qué sirvió la llamada) yfallback(capacitycuando se rechazó flex). - El ahorro. En lo que ahorró el enrutado, una llamada flex se compara con el modelo de referencia de tu key a su precio flex, o a su precio estándar cuando ese modelo no tiene nivel flex, así que el descuento del propio proveedor nunca cuenta como ahorro. Ver Facturación.
- División y enrutado. Los pasos previos de una división (el extracto y las comprobaciones) se ejecutan en el nivel estándar; solo la respuesta puede ir en flex.
El trabajo que puede esperar un día va por Lotes (/v1/files y /v1/batches), donde cada línea se cobra a los precios por lotes de los proveedores, o por una response en segundo plano con un deadline de 24 horas o más, que se suma al siguiente lote de tu organización sin archivo. Una llamada síncrona con ese plazo no puede esperar tanto en una sola conexión, así que se sirve en el nivel flex cuando el modelo lo tiene (en estándar si no) y zabio.tier lo indica: {"requested": "batch", "applied": "flex", "fallback": "synchronous"}.
Imágenes
Section titled “Imágenes”Los mensajes user pueden contener partes image_url:
{"role": "user", "content": [ {"type": "text", "text": "¿Qué hay en esta imagen?"}, {"type": "image_url", "image_url": {"url": "https://example.com/foto.jpg"}}]}url es una URL http(s) o un data URI con la forma data:image/<tipo>;base64,<datos>. Zabio descarga las URL y envía los bytes al proveedor, así que todos los proveedores reciben la misma entrada. Reglas para las URL:
- solo hosts públicos; se rechazan las direcciones de rangos privados, loopback, link local u otros rangos internos
- como máximo 20 MB por imagen, hasta 20 imágenes por petición
- el servidor debe responder con
image/png,image/jpeg,image/webpoimage/gif - como máximo 3 redirecciones, solo
http(s), 15 segundos de tiempo límite
Los fallos devuelven 400 invalid_image_url con param apuntando a la parte que falló. Una petición con imágenes solo se enruta a modelos con visión; un modelo nombrado sin visión (zabio.capabilities.vision a false en GET /v1/models) responde 400 unsupported_for_model nombrando el modelo, antes de enviar nada a un proveedor, sea cual sea el ajuste de fallback de la key.
Los mensajes user pueden contener partes input_audio, con la forma que envían los SDK de OpenAI:
{"role": "user", "content": [ {"type": "text", "text": "¿Qué se dice en este clip?"}, {"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}]}data es el audio en base64 sin más (no un data URL) y format es wav o mp3. El clip se envía al modelo tal cual, salvo que a una cabecera WAV escrita por una grabadora en streaming se le fijan sus dos campos de tamaño a partir de la longitud del clip; Zabio lee su cabecera para conocer la duración y el contenedor, y nada se transcodifica. Reglas:
- el límite de audio de una petición depende del modelo: los modelos Gemini de Google aceptan hasta 100 MB de audio decodificado por petición, y todos los demás 20 MB. Más de lo que acepta el modelo responde 413
media_too_largeantes de enviar nada a un proveedor, y con un modelo nombrado el mensaje indica su límite.autoelige entre los modelos que aceptan el audio de la petición - el cuerpo de una petición está limitado a 32 MB, que son unos 25 MB de audio decodificado, así que una sola petición lleva como máximo eso. Más audio solo llega a un modelo Gemini en la Responses API, donde los clips de los turnos guardados de una conversación se envían de nuevo con cada turno posterior y cuentan para el límite
- otro
formatresponde 400unsupported_value; un data URL o unos bytes que no son base64 responden 400invalid_value; unwavque en realidad es unmp3, o al revés, responde 400invalid_valueenformat - una petición con audio solo se enruta a modelos que aceptan audio de entrada: en
GET /v1/modelstienenzabio.capabilities.audio_inputatrue. Hoy songemini-3.8-flash,gemini-3.6-flash,gemini-3.5-flash-lite,gemini-3-flash-previewygemini-3.1-flash-litede Google, ygpt-audio-1.5,gpt-audioygpt-audio-minide OpenAI (los dos últimos hasta su apagado el 2027-01-20).autoelige entre los modelos Gemini; los de OpenAI se llaman por su nombre - un modelo nombrado que no acepta audio responde 400
unsupported_for_modelnombrando el modelo, antes de enviar nada a un proveedor - para una respuesta en audio, ver Respuestas en audio
El proveedor cuenta el clip en tokens de audio y los comunica en usage.prompt_tokens_details.audio_tokens, dentro de prompt_tokens; se cobran al precio de audio del modelo (zabio.pricing.audio_input en GET /v1/models, por millón de tokens de audio), y el texto al precio de texto. En los modelos Gemini, el audio que el proveedor leyó de su caché se cuenta en prompt_tokens_details.cached_tokens y se cobra al precio de caché, o al precio de caché para audio del modelo cuando tiene uno (zabio.pricing.cache_read_audio en GET /v1/models), y audio_tokens es el resto, así que ningún token se cobra dos veces. El detalle de una llamada en Registro y la exportación CSV de tus llamadas indican ese audio en caché aparte de los demás tokens en caché (tokens_cached_audio_read en la exportación), así que puedes sumar lo que costó la llamada a partir de sus tokens. Google cuenta 25 tokens por segundo de audio, así que un minuto son unos 1,500 tokens. Antes de la llamada, Zabio estima el clip a la tasa del modelo para los límites de ritmo y la comprobación de saldo, a partir de la duración que indica su cabecera.
En este endpoint el clip nunca se guarda ni se registra: va al proveedor que responde (zabio.vendor) y se descarta al terminar la llamada. Cuando una petición a un modelo Gemini lleva más de 20 MB de medios, Google recibe sus clips por su propio servicio de archivos, y Zabio los borra allí en cuanto llega la respuesta. Con el registro de cuerpos activado en la key, la petición guardada conserva el formato, el tamaño y la duración del clip, nunca sus bytes. En la Responses API un turno guardado conserva el clip, cifrado, durante la retención de la conversación, para que los turnos siguientes puedan seguir oyéndolo.
Respuestas en audio
Section titled “Respuestas en audio”Un modelo de chat que responde en audio dice su respuesta en voz cuando la petición lo pide, con la forma que envían los SDK de OpenAI:
{"model": "gpt-audio-1.5", "modalities": ["text", "audio"], "audio": {"voice": "alloy", "format": "wav"}, "messages": [{"role": "user", "content": "Cuéntame un chiste corto."}]}La respuesta lleva el audio en choices[0].message.audio: data (el audio en base64, en el formato pedido), transcript (sus palabras), e id y expires_at (ver un turno siguiente, más abajo); content es null. Reglas:
- los modelos que responden en audio tienen
zabio.capabilities.audio_outputatrueenGET /v1/models, sus formatos enaudio_formats, los formatos en que hacen streaming enaudio_stream_formatsy sus voces envoices. Hoy songpt-audio-1.5,gpt-audioygpt-audio-minide OpenAI (los dos últimos hasta su apagado el 2027-01-20) yqwen3.5-omni-plus,qwen3.5-omni-plus-2026-03-15yqwen3.5-omni-flashde Alibaba (procesados fuera de China continental; ver Qwen Omni, más abajo;qwen3.5-omni-flash-2026-03-15responde solo en texto, porque no envía audio), con sus precios de audio en Respuestas en audio de la página de modelos formateswav,mp3,flac,opus,pcm16(muestras de 16 bits sin cabecera) oaac, según lo que ofrezca el modelo;voicees una de las voces del modelo por su nombre (en los modelos de OpenAI:alloy,ash,ballad,cedar,coral,echo,fable,marin,nova,onyx,sage,shimmeryverse; en los modelos Qwen Omni las 56 voces devoices, comoTinaoLiora Mira, escritas como aparecen). Un objeto de voz personalizada se rechaza con 400unsupported_value, igual que un formato o una voz que el modelo nombrado no ofrece, con lo que ofrece en el mensaje- un modelo nombrado que no responde en audio responde 400
unsupported_for_model, antes de enviar nada a un proveedor, sea cual sea el ajuste de respaldo de la key; un respaldo solo lleva la petición a otro modelo que responde en el mismo formato y con la misma voz autotodavía no responde en audio: una petición de audio aautoo a una de sus líneas responde 400unsupported_for_model; nombra el modelomodalitiesdebe ser["text", "audio"]: el audio solo responde 400invalid_value, porque los modelos lo rechazan- una respuesta en audio no puede ir en un batch, y la Responses API responde en texto (400
unsupported_parameterenmodalitiesoaudio)
Streaming. Los modelos de OpenAI hacen streaming de una respuesta solo en pcm16: stream: true con otro formato responde 400 unsupported_value en audio.format, antes de enviar nada a un proveedor; sin stream funcionan todos los formatos. Con stream: true el audio llega en chunks choices[0].delta.audio, con la forma de OpenAI: trozos de data y de transcript, el id y, al final, un chunk solo con expires_at. Decodifica cada trozo de data desde base64 y une los bytes en orden; pcm16 se puede reproducir a medida que llega.
Qwen Omni. Los modelos Qwen Omni responden en audio solo cuando la petición hace streaming (zabio.capabilities.audio_stream_only en GET /v1/models): sin stream: true, una petición con la modalidad de audio responde 400 unsupported_value en stream, antes de enviar nada a un proveedor, porque el proveedor respondería en texto y cobraría igual el audio. Una petición sin la modalidad de audio se atiende con o sin streaming. Responden solo en pcm16 (24 kHz, 16 bits, mono). Las palabras de la respuesta llegan en content (en delta.content con streaming), no en transcript. Aceptan texto de entrada, no imágenes, audio, video ni herramientas, y el id de audio de una respuesta anterior se rechaza: envía el content de la respuesta anterior como content del asistente.
Un turno siguiente. Para seguir después de una respuesta en audio, devuelve el turno del asistente como {"role": "assistant", "audio": {"id": "<el audio.id de la respuesta>"}}. El proveedor guarda ese audio hasta expires_at y Zabio no guarda nada, así que esa petición debe nombrar un modelo del proveedor que dio la respuesta (a auto, o a un modelo de otro proveedor, responde 400 unsupported_for_model), y pasado expires_at el proveedor rechaza el id. Enviar el transcript como content del asistente funciona con cualquier modelo.
Cobro. El proveedor informa el audio de la respuesta en usage.completion_tokens_details.audio_tokens y su texto en text_tokens, ambos dentro de completion_tokens. Los tokens de audio se cobran al precio de salida de audio del modelo (zabio.pricing.audio_output en GET /v1/models, por millón de tokens de audio), el texto a su precio de salida, más la tarifa como en toda llamada; si un proveedor no informa el recuento de audio, toda la salida se cobra al precio del audio, y los tokens de audio que un proveedor informa para una respuesta que no llevó audio no se cobran. En los modelos Qwen Omni el texto de una respuesta que lleva audio es gratis y solo se cobra su audio, como lo cobra Alibaba (zabio.pricing.text_free_with_audio en GET /v1/models); una respuesta solo en texto paga el precio de salida. Antes de la llamada, la comprobación de saldo cuenta todo el presupuesto de salida al precio del audio: tu max_tokens, o al menos 2,048 tokens si no envías ninguno; cuando tu saldo no alcanza para toda la salida del modelo, al modelo se le envía la salida que el saldo puede pagar. Un stream que termina sin su uso se cobra según lo que te llegó, marcado como estimado.
Nunca se guarda. La respuesta en audio va del proveedor a ti; Zabio no guarda el audio, ni en un archivo ni en un log. Con el registro de cuerpos activado en la key, la respuesta guardada conserva su transcripción, su id y su tamaño en bytes, nunca el audio.
Los mensajes user pueden llevar partes video_url, con la forma de la parte de imagen y una forma de archivo al lado:
{"role": "user", "content": [ {"type": "text", "text": "¿Qué pasa en este video?"}, {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}]}video_url.url es una de tres cosas: una data URL (data:video/mp4;base64,..., también video/quicktime y video/webm), una URL https o una URL pública de YouTube (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). En lugar de una url, video_url.file_id puede nombrar un archivo que subiste a POST /v1/files con propósito user_data; la key debe poder leerlo. Los videos son MP4, MOV o WebM; Zabio lee la cabecera del archivo para conocer su formato y su duración y no cambia nada en él. Reglas:
- Zabio descarga una URL https con las reglas de las URL de imagen: solo direcciones públicas, 15 segundos, como máximo 20 MB. Para un video más grande, súbelo y envía su
file_id, o envía su URL a un modelo Qwen por nombre (la regla siguiente) - Zabio no descarga un video https de más de 20 MB enviado a un modelo Qwen por nombre: Alibaba lo descarga desde tu URL, hasta los 2 GB que Alibaba indica como límite. La URL debe ser accesible desde la internet pública, y Alibaba pide que su servidor indique el tamaño y el tipo del archivo (
Content-LengthyContent-Type). Zabio lee solo el primer 1 MB del archivo, con las mismas reglas que cualquier descarga, para conocer su formato y su duración. Un MP4 o MOV guardado para streaming (con el índice al principio del archivo, lo que suele llamarse fast start) indica ahí su duración. Uno con el índice al final no la indica, y se estima en diez minutos. Cualquier otro modelo responde 400invalid_video_urla un video https de más de 20 MB, y tambiénauto, que no elige los modelos Qwen - como máximo 10 videos por petición, y como máximo 100 MB de video en total (413
media_too_large). Una data URL cuenta además para el cuerpo de 32 MB de la petición, así que un video de más de unos 24 MB va como archivo - una petición con video solo se enruta a modelos que aceptan video:
zabio.capabilities.video_inputestrueen ellos enGET /v1/models. Hoy songemini-3.8-flash,gemini-3.6-flash,gemini-3.5-flash-lite,gemini-3-flash-previewygemini-3.1-flash-litede Google, yqwen3.8-omni-flash,qwen3.8-flashyqwen3.7-plusde Alibaba (tambiénqwen3.7-plus@alibaba-us), y sus modelos Qwen 3.6 y 3.5qwen3.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-a3byqwen3.5-27b.autoelige entre los modelos Gemini; los modelos Qwen se llaman por su nombre - un modelo nombrado que no acepta video responde 400
unsupported_for_modelnombrando el modelo, antes de enviar nada a un proveedor - las URL de YouTube y los videos WebM van solo a los modelos Gemini. Los modelos Qwen aceptan un video enviado como datos solo por debajo de 10 MB de base64 (unos 7.5 MB de video); un video más grande les llega como URL https, que Zabio pasa para que el proveedor la descargue. Un modelo Qwen nombrado al que se pide otra cosa responde 400
unsupported_valuediciendo por qué - un video no puede ir en un lote ni en una Response en segundo plano: Zabio no guarda videos para después
El proveedor cuenta el video en tokens de entrada, dentro de usage.prompt_tokens, y se cobran al precio de entrada del modelo; Un clip de prueba contó unos 65 tokens por segundo en Gemini sin sonido y unos 90 con sonido, y en los modelos Qwen un token por cada 32 por 32 píxeles de un fotograma, un fotograma por segundo: unos 220 por segundo a 360p, unos 400 a 480p y unos 600 a 720p o más, así que un minuto en Gemini son unos 4,000 a 6,000 tokens; la página de Google indica unos 100 por segundo en resolución baja y 300 en alta. Gemini cuenta el sonido de un video dentro de los tokens del video, al precio de entrada. El modelo Omni de Alibaba cuenta aparte el sonido de un video, en usage.prompt_tokens_details.audio_tokens, que se cobra al precio de audio del modelo. Los demás modelos Qwen no escuchan el sonido de un video y no cuentan ninguno. Antes de la llamada, Zabio estima el video a la tasa del modelo para los límites de ritmo y la comprobación de saldo, a partir de la duración que indica su cabecera; un video cuya duración Zabio no puede leer (una URL de YouTube, un WebM grabado en directo, un video https de más de 20 MB cuya duración no está al principio del archivo) se estima en diez minutos. Una llamada cuyo stream termina antes de que el proveedor informe su uso se cobra según el recuento propio de Zabio: la duración que Zabio leyó, a no más de 220 tokens por segundo en los modelos Qwen, o 594 cuando Zabio leyó una imagen de 720p o mayor al principio del archivo.
Zabio nunca guarda un video: va al proveedor que responde (zabio.vendor) y se descarta al terminar la llamada. Google recibe un video de más de 20 MB por su propio servicio de archivos, y Zabio lo borra allí en cuanto llega la respuesta. Un video https de más de 20 MB enviado a un modelo Qwen lo descarga Alibaba desde tu URL; Zabio lee su primer 1 MB y no conserva nada de él. Nada del video se registra; con el registro de cuerpos activado en la key, la petición guardada conserva el formato, el tamaño y la duración del video, nunca el video ni su dirección. En la Responses API un turno guardado conserva solo esa misma referencia, así que un turno posterior de la conversación no vuelve a ver el video.
Herramientas
Section titled “Herramientas”Las herramientas de tipo función funcionan como en OpenAI. Envía tools, recibe tool_calls en el mensaje del asistente con finish_reason: "tool_calls", y responde con mensajes tool que lleven tool_call_id. Los argumentos son siempre una cadena JSON ({} cuando está vacía). Las peticiones con herramientas solo se enrutan a modelos que las soportan.
Herramientas en los modelos Gemini
Section titled “Herramientas en los modelos Gemini”Los modelos Gemini de Google aceptan un subconjunto de JSON Schema en los parameters de una herramienta. Zabio convierte cada esquema al enviarlo a un modelo Gemini, así que los esquemas que envían los SDK de OpenAI y de Anthropic y Claude Code funcionan sin cambios: las referencias ($ref a $defs) se escriben en su lugar, una lista de tipos pasa a ser un tipo marcado como nullable, const pasa a ser un enum de un valor, oneOf pasa a ser anyOf, y el exclusiveMinimum o exclusiveMaximum de un entero pasa a ser el minimum o maximum del siguiente número entero. Las palabras clave sin equivalente en Gemini se omiten en la llamada, y las que llevaban una regla aparecen en zabio.ignored_parameters como tools.parameters.<palabra clave>, una vez cada una: por ejemplo tools.parameters.additionalProperties, de modo que el modelo puede añadir una propiedad que tu esquema cerraba. Un format que Gemini no conoce, un enum de números, multipleOf, uniqueItems y un límite sobre un número decimal se repiten en la descripción del campo, para que el modelo los siga leyendo. Las anotaciones como $schema, $id y $comment se omiten sin mencionarlas. Una herramienta sin parámetros se declara sin ninguno.
Un esquema que se refiere a sí mismo (un $ref recursivo, como un árbol cuyos hijos son árboles) no se puede escribir para Gemini. Con auto, los modelos Gemini quedan fuera para esa petición y responde otro modelo; una petición que nombra un modelo Gemini recibe 400 unsupported_parameter con el nombre de la herramienta y de la palabra clave, y con ese 400 no se envía nada a Google ni se factura nada.
Salida estructurada
Section titled “Salida estructurada”response_format.type |
Comportamiento |
|---|---|
text |
por defecto |
json_object |
OpenAI, Google, DeepSeek, xAI, Mistral AI y Together AI usan su modo JSON nativo. Anthropic no tiene modo JSON object: Zabio añade una instrucción de sistema que pide exactamente un objeto JSON y nada más, arranca la respuesta dentro del objeto en los modelos que lo permiten, y elimina el bloque de código Markdown alrededor del objeto cuando el modelo lo añade de todas formas. Es un mecanismo de mejor esfuerzo por construcción. Valida la salida por tu parte cuando la respuesta pueda venir de un modelo de Anthropic, y prefiere json_schema siempre que conozcas la forma que quieres |
json_schema |
{"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}. Se traduce a la salida estructurada nativa de cada proveedor. schema es obligatorio. Solo se enruta a modelos con soporte json_schema (no a los modelos directos de DeepSeek, ni a los modelos Qwen de Alibaba Cloud que no aplican un esquema; zabio.capabilities.json_schema en GET /v1/models indica qué modelos lo admiten). Con Jev, el modelo de decisión (jev-1.14.0 o jev-1.13.0), las propiedades del esquema son las preguntas que Jev responde, cada una con su probabilidad en zabio.decision; ver Modelos de decisión |
La respuesta
Section titled “La respuesta”Un objeto chat.completion estándar. usage.prompt_tokens cuenta todos los tokens de entrada, en caché o no, para que los totales coincidan con lo que procesó el proveedor; usage.prompt_tokens_details.cached_tokens es la parte en caché, y usage.completion_tokens_details.reasoning_tokens es el recuento del proveedor de tokens de razonamiento dentro de completion_tokens, presente cuando el proveedor lo informa. finish_reason es stop, length, tool_calls o content_filter. Zabio sirve exactamente una opción. Un modelo de razonamiento que gasta todo su presupuesto de salida pensando devuelve una respuesta vacía con finish_reason: "length": sube max_tokens para que deje sitio a la respuesta por encima del razonamiento, o baja reasoning_effort.
El objeto zabio de la respuesta
Section titled “El objeto zabio de la respuesta”| Campo | Tipo | Significado |
|---|---|---|
vendor |
cadena | quién sirvió la llamada: anthropic, openai, google, deepseek, xai, mistral, together o typesafe |
model_served |
cadena | el modelo que respondió; difiere del model que enviaste con auto y con los fallbacks |
routing |
objeto o ausente | line, task, task_type (el tipo de trabajo como etiqueta, ver Tipos de trabajo), difficulty, band, stakes, biased, cell, confidence (de 0 a 1), reason (la frase del clasificador), trigger (por qué se tomó la decisión; consulta Modelos y enrutado), classifier (quién decidió: typesafe/jev-1.13.0, o el clasificador de texto al que se recurrió; ausente en modelos explícitos), effort (el ajuste de razonamiento elegido junto con el modelo), effort_reason (por qué) y sticky (solo presente cuando la caché de prompt caliente de la sesión decidió la elección: el modelo que se mantuvo y el que habría elegido el precio en frío). Ausente en modelos explícitos sin información de enrutado |
reasoning |
objeto | requested (el nivel que enviaste, omitido si ninguno) y applied (lo que recibió el modelo servido: default, off, el nombre del nivel del proveedor, budget N, on, always on o not supported) |
cost_micros |
entero | lo que se te facturó, en millonésimas de dólar (1,000,000 micros = 1 USD) |
cost |
objeto | el desglose: vendor_micros (precio de lista del proveedor), service_fee_micros, call_fee_micros (la cantidad fija que paga una vez una petición auto, el precio de la elección automática del modelo; 0 en un modelo con nombre), savings_fee_micros y classifier_micros (ambos siempre 0, se mantienen para que los clientes existentes sigan leyéndolos). Solo el coste: lo que ahorró el enrutado se calcula para un periodo, nunca por llamada (consulta El ahorro de un periodo) |
byok |
booleano | true cuando la llamada usó tu propia key del proveedor |
cache |
objeto | read_tokens, write_tokens, ttl_applied (5m, 1h o none) y applied (none, zabio o vendor_automatic: quién guardó en caché, consulta la tabla por proveedor) |
session_id |
cadena | repite el id de sesión que enviaste |
escalated_from |
cadena | la línea que aplicó Zabio (cheap, balanced o best, también con auto a secas) y el modelo cuya respuesta auto sustituyó: en la Responses API cuando ese modelo pidió uno más potente, y en cualquier petición sin streaming cuando su respuesta no pasó la comprobación de Zabio |
compacted |
booleano | solo Responses API: el historial guardado se resumió antes de este turno |
vendor_stop_reason |
cadena | el motivo de parada propio del proveedor, para depurar |
ignored_parameters |
lista | campos de la petición que Zabio aceptó e ignoró |
dropped_parameters |
lista | parámetros de muestreo que el modelo que respondió no admite (temperature, top_p), omitidos de su petición; también la cabecera x-zabio-dropped-params |
attempts |
entero | cuántos proveedores se probaron antes de que uno respondiera |
decision |
objeto | cuando respondió Jev (jev-1.14.0 o jev-1.13.0), nombrado o elegido por auto para una tarea de clasificación: las probabilidades calibradas detrás de cada propiedad de la respuesta, ver Modelos de decisión |
no_answer |
string | presente cuando la petición terminó sin respuesta, con el presupuesto de salida gastado en razonamiento, o la entrada no dejó espacio para la respuesta en la ventana de contexto del modelo: qué pasó, qué cambiar y si se cobró (no, dentro de los límites de Respuestas comprobadas) |
split |
objeto | presente mientras división y enrutado está activo: applied (true cuando la respuesta vino de un extracto de tu fuente), pattern (distill), reason (por qué no se dividió la petición: named_model, opt_out, not_eligible, below_threshold, jev_no, jev_failed, price_check), steps (cada llamada de la división: role questions, extract, check o answer, con vendor, model, input_tokens, output_tokens, micros a precio de lista y billed), excerpt (lines_kept, lines_total, tokens, verbatim_rate), check_p (la probabilidad de la comprobación) y fallback (la salvaguarda que mandó la petición entera). Ver División y enrutado |
tier |
objeto | el nivel de servicio: requested (standard, flex o batch, a qué se tradujo tu deadline: flex a partir de 15 minutos, batch a partir de 24 horas), applied (qué sirvió la llamada) y fallback (capacity cuando se pidió flex y el proveedor lo rechazó, de modo que el nivel estándar sirvió y fue el facturado; synchronous cuando el plazo pedía lotes en una llamada síncrona, que no puede esperar un día, así que sirvió flex o estándar). Ver Nivel flex |
search |
objeto | presente en una llamada que podía buscar en la web: form (native: buscó el propio proveedor del modelo), mode (tool), engine (el proveedor), searches (las búsquedas que contó el proveedor), max_uses (el máximo que la llamada podía hacer) y cost_micros (la línea de búsqueda de la factura, dentro del cost_micros de arriba; cost.search_micros y cost.search_fee_micros son sus partes). Ver Búsqueda web |
plan |
objeto | presente en una llamada servida con los límites de Free (consulta Facturación): tier (free), reason (free_plan, la organización nunca ha recargado; zero_balance, una organización de pago en cero que continúa en el nivel gratuito), paid_would_use (con auto, el modelo que habría recibido una cuenta de pago, cuando es distinto del que respondió) y topup_url. Ausente en una llamada de pago. No confundir con tier, el nivel de procesamiento del proveedor |
Los campos con valor vacío se omiten, así que comprueba su presencia.
Cabeceras de respuesta
Section titled “Cabeceras de respuesta”| Cabecera | Significado |
|---|---|
x-request-id |
id para citar en las consultas a soporte |
x-zabio-vendor |
igual que zabio.vendor. En una llamada cuyo 200 salió antes de la respuesta (ver Llamadas largas) no aparece, así que lee proveedor, modelo y enrutado del objeto zabio del cuerpo |
x-zabio-byok |
true cuando se usó tu propia key del proveedor |
x-zabio-searches |
las búsquedas web que el proveedor contó en la llamada; solo en una respuesta sin streaming que pidió búsqueda web |
x-zabio-balance-micros |
el saldo de créditos de tu organización tras la comprobación de admisión |
x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests |
el cupo de peticiones por minuto de la key |
x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-tokens |
el cupo de tokens por minuto de la key. Se cobra por adelantado con la estimación de entrada más el presupuesto de salida, limitado a lo que el modelo servido puede producir, y se ajusta tras la llamada; un max_tokens muy por encima de lo que la tarea necesita puede agotar el límite antes de tiempo, así que ponlo cerca de lo que necesitas |
x-zabio-quota-scope, x-zabio-quota-limit, x-zabio-quota-remaining |
presentes cuando se aplica un límite de gasto a la key (key, en su periodo) o la cuota mensual del miembro que la creó (member) |
x-zabio-plan |
free en toda llamada servida con los límites de Free; ausente en una llamada de pago |
x-ratelimit-limit-requests-day, x-ratelimit-remaining-requests-day, x-ratelimit-reset-requests-day |
el día del plan Free: 100 peticiones correctas, las que quedan y el tiempo hasta las 00:00 UTC. Solo con x-zabio-plan: free; en esas llamadas x-ratelimit-*-requests es el cupo del minuto de Free (20), más estricto que el propio de la key |
x-zabio-free-limit |
en un 429 o 403 free_tier_limit, qué límite se alcanzó: requests_per_day, requests_per_minute, daily_cost, input_tokens, max_tokens, members o api_keys |
Retry-After |
segundos a esperar, en 429 y en los 5xx reintentables |
Server-Timing |
lo que tardó cada etapa de la petición; ver Tiempos del servidor más abajo |
Consulta Errores para saber qué pasa cuando se alcanza un límite.
Tiempos del servidor
Section titled “Tiempos del servidor”Las respuestas de /v1 llevan la cabecera estándar Server-Timing: el tiempo que Zabio pasó en cada etapa de tu petición, en milisegundos. Una petición rechazada en la comprobación de la API key no la lleva.
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| Entrada | Qué mide |
|---|---|
auth |
la comprobación de tu API key |
admission |
las comprobaciones de saldo, de límite de peticiones, de límite de gasto y del plan Free |
routing |
la elección del modelo: en auto, clasificar la tarea y elegir el modelo; en un modelo con nombre, solo la elección |
vendor_first_byte |
desde la primera petición de Zabio a un proveedor hasta el primer byte de la respuesta que recibiste, con cualquier intento fallido en otro modelo antes de ella |
vendor_rest |
desde ese primer byte hasta el último byte del proveedor |
after_vendor |
desde el último byte del proveedor hasta las cabeceras: lo que hizo Zabio antes de responder |
La cabecera sale con el código de estado, así que lleva las etapas terminadas en ese momento. Las cabeceras de una respuesta en streaming salen cuando empieza la respuesta, así que su cabecera termina en vendor_first_byte; igual en una llamada cuyo 200 salió antes de la respuesta (ver Llamadas largas). Una etapa a la que la petición no llegó, porque se rechazó antes, no aparece. El tiempo entre etapas, como leer el cuerpo de tu petición, no está en ninguna entrada, así que las entradas suman menos que la llamada entera. La cabecera solo lleva duraciones, nada de tu organización ni de tu petición. La red entre tú y Zabio puede añadir entradas con otros nombres; ignóralas.
Con el SDK de OpenAI para Python, léela de la respuesta sin procesar:
raw = client.chat.completions.with_raw_response.create( model="auto", messages=[{"role": "user", "content": "Hola"}],)print(raw.headers.get("server-timing"))completion = raw.parse()