Ir al contenido
Zabio está en beta: los modelos, los precios y las funciones pueden cambiar. Cuéntanos qué falla en hello@zabio.ai.

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.

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

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

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.

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 200 y 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 fija stop en o1 u o3-mini, solo se responde cuando el modelo ha terminado de pensar, así que su 200 sale 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 objeto error (message, type, code, request_id), sin choices. Comprueba si hay error antes de leer choices: 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 con finish_reason: "error", y después data: [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 200 y 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 objeto zabio del cuerpo, como siempre.

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.

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.

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, o3 y o4-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é de gpt-5.4 y de o4-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-latest y 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í que auto puede 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.fallback es entonces capacity.
  • 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.tier indica requested (flex o standard, a qué se tradujo tu plazo), applied (qué sirvió la llamada) y fallback (capacity cuando 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"}.

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/webp o image/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_large antes de enviar nada a un proveedor, y con un modelo nombrado el mensaje indica su límite. auto elige 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 format responde 400 unsupported_value; un data URL o unos bytes que no son base64 responden 400 invalid_value; un wav que en realidad es un mp3, o al revés, responde 400 invalid_value en format
  • una petición con audio solo se enruta a modelos que aceptan audio de entrada: en GET /v1/models tienen zabio.capabilities.audio_input a true. Hoy son gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3-flash-preview y gemini-3.1-flash-lite de Google, y gpt-audio-1.5, gpt-audio y gpt-audio-mini de OpenAI (los dos últimos hasta su apagado el 2027-01-20). auto elige entre los modelos Gemini; los de OpenAI se llaman por su nombre
  • un modelo nombrado que no acepta audio responde 400 unsupported_for_model nombrando 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.

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_output a true en GET /v1/models, sus formatos en audio_formats, los formatos en que hacen streaming en audio_stream_formats y sus voces en voices. Hoy son gpt-audio-1.5, gpt-audio y gpt-audio-mini de OpenAI (los dos últimos hasta su apagado el 2027-01-20) y qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15 y qwen3.5-omni-flash de Alibaba (procesados fuera de China continental; ver Qwen Omni, más abajo; qwen3.5-omni-flash-2026-03-15 responde solo en texto, porque no envía audio), con sus precios de audio en Respuestas en audio de la página de modelos
  • format es wav, mp3, flac, opus, pcm16 (muestras de 16 bits sin cabecera) o aac, según lo que ofrezca el modelo; voice es 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, shimmer y verse; en los modelos Qwen Omni las 56 voces de voices, como Tina o Liora Mira, escritas como aparecen). Un objeto de voz personalizada se rechaza con 400 unsupported_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
  • auto todavía no responde en audio: una petición de audio a auto o a una de sus líneas responde 400 unsupported_for_model; nombra el modelo
  • modalities debe ser ["text", "audio"]: el audio solo responde 400 invalid_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_parameter en modalities o audio)

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-Length y Content-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 400 invalid_video_url a un video https de más de 20 MB, y también auto, 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_input es true en ellos en GET /v1/models. Hoy son gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3-flash-preview y gemini-3.1-flash-lite de Google, y qwen3.8-omni-flash, qwen3.8-flash y qwen3.7-plus de Alibaba (también qwen3.7-plus@alibaba-us), y sus modelos Qwen 3.6 y 3.5 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 y qwen3.5-27b. auto elige entre los modelos Gemini; los modelos Qwen se llaman por su nombre
  • un modelo nombrado que no acepta video responde 400 unsupported_for_model nombrando 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_value diciendo 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.

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.

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.

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

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.

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.

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.

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