Responses API y conversaciones
POST /v1/responses implementa el formato de la Responses API de OpenAI, así que los SDK de OpenAI funcionan sin cambios. A diferencia de chat completions, que no guarda nada, una response se guarda en el lado de Zabio junto con la conversación a la que pertenece. Tú envías el mensaje nuevo; Zabio monta el historial, lo enruta, guarda la respuesta y te la devuelve.
Para la forma exacta de cada petición y respuesta, con ejemplos en curl, Python y Node, consulta la Referencia de la API.
La key necesita el scope conversations (las keys lo tienen por defecto). Una key sin él recibe 403 insufficient_scope.
Crear una response
Section titled “Crear una response”from openai import OpenAI
client = OpenAI(base_url="https://api.zabio.ai/v1", api_key="insert your zabio.ai key here")
first = client.responses.create(model="auto", input="Me llamo Ana. Recuérdalo.")second = client.responses.create(model="auto", input="¿Cómo me llamo?", previous_response_id=first.id)print(second.output_text)| Campo | Tipo | Notas |
|---|---|---|
model |
cadena | un id del catálogo o auto, auto/best, auto/balanced, auto/cheap. Si se omite, es auto |
input |
cadena o lista de items | una cadena es un mensaje de usuario. Items: {"role": "user" o "assistant" o "system" o "developer", "content": cadena o partes}, {"type": "function_call_output", "call_id", "output"}, {"type": "function_call", "call_id", "name", "arguments"}. Partes de contenido: input_text, input_image (image_url), input_audio (input_audio con data en base64 y format wav o mp3, como en chat completions; solo los modelos con audio de entrada lo aceptan), input_video (video_url como data URL, URL https o URL de YouTube, o file_id, como en chat completions; solo los modelos con video de entrada lo aceptan) |
instructions |
cadena | instrucciones de sistema para este turno (se guardan con el turno) |
previous_response_id |
resp_... |
continúa desde esa response. Apuntar a una response antigua crea una rama: la conversación conserva su hilo y esta response empieza uno nuevo |
conversation |
conv_... o {"id": ...} |
continúa desde el último turno de la conversación. Con previous_response_id, ambos deben pertenecer a la misma conversación |
store |
booleano, por defecto true | false calcula el turno a partir del historial guardado y no guarda nada. El id de la response no se puede recuperar después |
tools, tool_choice |
herramientas de tipo función: {"type": "function", "name", "description", "parameters"}, y {"type": "web_search"}, ver Búsqueda web; tool_choice es auto, none, required, {"type": "function", "name"} o {"type": "web_search"} |
|
max_output_tokens, temperature, top_p, parallel_tool_calls |
muestreo; max_output_tokens no tiene valor por defecto: si no lo fijas, Zabio no añade ningún límite de salida. Un valor por encima de la salida máxima del modelo servido se baja a ese límite, en cada intento |
|
text.format |
{"type": "json_object"} o {"type": "json_schema", "name", "schema", "strict"}. Aplica la advertencia sobre json_object en Anthropic de Chat completions |
|
reasoning.effort |
none, minimal, low, medium, high o xhigh, aplicado al control propio del modelo servido; zabio.reasoning indica lo que se aplicó |
|
metadata |
objeto | hasta 16 claves, keys de 64 caracteres, valores de 512 caracteres |
stream |
booleano | server sent events, ver más abajo |
background |
booleano, por defecto false | ejecuta el turno más tarde y devuelve al momento la response con status: "queued"; consulta GET /v1/responses/{id} para leer el resultado. Necesita store true y no admite stream. Ver Responses en segundo plano |
modalities, audio |
la Responses API responde en texto: cualquier modalities distinta de ["text"], o un objeto audio, responde 400 unsupported_parameter. Para una respuesta en audio usa chat completions, como hacen los propios modelos de audio de OpenAI |
|
zabio |
objeto | session_id, vendors, fallback, cache, split, deadline como en chat completions, más retention_days (de 0 a 365, para una conversación creada por esta llamada) y compaction (auto u off) |
Sin previous_response_id ni conversation se crea una conversación nueva para la response cuando store es true.
El objeto response
Section titled “El objeto response”{ "id": "resp_...", "object": "response", "created_at": 1758283200, "status": "completed", "model": "claude-haiku-4-5", "output": [ {"type": "message", "id": "msg_...", "status": "completed", "role": "assistant", "content": [{"type": "output_text", "text": "...", "annotations": []}]}, {"type": "function_call", "id": "fc_...", "call_id": "call_...", "name": "get_weather", "arguments": "{\"city\":\"Lima\"}", "status": "completed"} ], "usage": {"input_tokens": 120, "input_tokens_details": {"cached_tokens": 100}, "output_tokens": 20, "output_tokens_details": {"reasoning_tokens": 0}, "total_tokens": 140}, "previous_response_id": null, "conversation": {"id": "conv_..."}, "metadata": {}, "store": true, "zabio": {"vendor": "anthropic", "model_served": "claude-haiku-4-5", "routing": {...}, "cost_micros": 63, "cost": {...}, "byok": false, "escalated_from": "", "compacted": false, "split": {...}}}status es completed, incomplete (la salida llegó a max_output_tokens; incomplete_details.reason lo indica; un modelo de razonamiento que gastó todo su presupuesto pensando termina así sin texto: sube max_output_tokens para que deje sitio a la respuesta por encima del razonamiento, o baja el esfuerzo de razonamiento) o failed; una response en segundo plano es también queued o cancelled, y lleva background: true. usage.output_tokens_details.reasoning_tokens es el recuento de razonamiento del proveedor cuando lo informa, si no 0. El objeto zabio es el que se describe en Chat completions, y aquí importan tres campos más:
escalated_from: se rellena cuando el primer modelo elegido porautopidió uno más potente, o cuando su respuesta no pasó la comprobación de Zabio, y la respuesta vino de otro modelo. El escalado en sí nunca aparece enoutput.compacted: se rellena cuando el historial guardado se resumió antes de este turno porque ya no cabía en la ventana de contexto del modelo.split: lo que hizo división y enrutado con este turno (ver División y enrutado), guardado con la response igual quecompacted. Solo se puede dividir el último mensaje del usuario del propio turno, nunca el historial guardado;zabio.split: "off"envía el turno entero.tier: el nivel de servicio de este turno (ver Nivel flex):requested,appliedyfallback, guardado con la response igual quesplit. Unzabio.deadlinede 15 minutos o más hace que el turno pueda servirse en el nivel flex del proveedor; uno de 24 horas o más pide el nivel de lotes, que solo una response en segundo plano puede esperar. En un turno síncrono con ese plazoappliedesflexostandardyfallbackessynchronous.plan: presente en un turno servido con los límites de Free (consulta Facturación, “El plan Free”):tier(free),reason(free_planozero_balance),paid_would_use(conauto, el modelo que habría recibido una cuenta de pago, cuando es distinto) ytopup_url. Una response en segundo plano lo lleva en el objeto en cola y en el final; un turno admitido con saldo se factura como de pago hasta el final aunque el saldo cruce el cero mientras se ejecuta.
Responses en segundo plano
Section titled “Responses en segundo plano”Envía background: true y la llamada devuelve al momento el objeto response con status: "queued", background: true y un output vacío. El turno se ejecuta más tarde; consulta GET /v1/responses/{id} hasta que el estado sea completed, incomplete, failed o cancelled, y lee entonces output, usage y zabio como en cualquier response. Todo lo demás del turno es igual: la conversación, previous_response_id, las herramientas, la compactación, las opciones zabio. background necesita store true (el valor por defecto; la response se guarda para poder consultarla) y no se puede combinar con stream. Un turno con una parte input_video no puede ir en segundo plano (400 unsupported_parameter en background): Zabio no guarda videos para después.
Dónde se ejecuta el turno depende de zabio.deadline:
- Un plazo de 24 horas o más con
autoo con un modelo que tiene nivel de lotes mete el turno en el siguiente lote de tu organización: las peticiones en segundo plano sueltas se agrupan durante hasta 15 minutos, o hasta que llegan 500, y se envían juntas como un lote del proveedor por modelo a los precios por lotes de los proveedores, la mitad del precio de lista más o menos. El resultado llega dentro de la ventana de 24 horas de los proveedores contada desde ese momento, normalmente mucho antes. El turno se factura exactamente como una línea de un lote: el precio por lotes por los tokens que usó, más las comisiones habituales.zabio.tieres{"requested": "batch", "applied": "batch"}. Antes de encolar el turno, su coste estimado se reserva en tu saldo como el de un lote; si la estimación supera tu saldo disponible, la llamada responde 402insufficient_creditsy no se guarda nada. - Cualquier otra petición en segundo plano se ejecuta en cuanto un worker la toma, con el mismo enrutado que una llamada síncrona: en el nivel flex a partir de un plazo de 15 minutos cuando el modelo lo tiene, en estándar si no. Un plazo de 24 horas o más con un modelo cuyo proveedor no tiene nivel de lotes se ejecuta también así, y lo dice:
zabio.tieres{"requested": "batch", "applied": "flex"(o"standard"), "fallback": "no_batch_tier"}. Nada pasa en silencio a un nivel más caro. La llamada tiene el tiempo límite de una llamada síncrona sin streaming: tras 20 minutos sin respuesta el turno terminafailedconrequest_timeout(ver Errores), o con el error de un intento que falló antes del límite. Los 20 minutos cuentan desde que empieza la llamada, no desde que el turno entró en cola.
El objeto en cola ya lleva zabio.tier con el nivel que recibió la petición; el objeto final lleva el que la sirvió.
Cancelar. POST /v1/responses/{id}/cancel termina un turno en cola, o uno que todavía espera a que se envíe su lote, con status: "cancelled" y sin facturar nada; sus entradas se quedan en la conversación con ese estado, como las de un turno fallido. Un turno que ya se está ejecutando como trabajo se corta y termina cancelled. Un turno ya enviado al proveedor del modelo dentro de un lote no se puede recuperar: la llamada responde 409 not_cancellable y la respuesta llega y se factura. Cancelar un turno que ya terminó devuelve el objeto tal cual; cancelar una response que no se creó con background responde 400 not_background.
Python
r = client.responses.create(model="auto", input="Resume este informe: ...", background=True, extra_body={"zabio": {"deadline": "24h"}})print(r.status) # queuedwhile r.status in ("queued", "in_progress"): time.sleep(60) r = client.responses.retrieve(r.id)print(r.status, r.output_text, r.model_extra["zabio"]["tier"])Node
let r = await client.responses.create({ model: "auto", input: "Resume este informe: ...", background: true, zabio: { deadline: "24h" } });while (r.status === "queued" || r.status === "in_progress") { await new Promise((ok) => setTimeout(ok, 60_000)); r = await client.responses.retrieve(r.id);}console.log(r.status, r.output_text, r.zabio.tier);Streaming
Section titled “Streaming”Con stream: true la respuesta es un stream de server sent events: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.output_item.done, response.function_call_arguments.delta, response.function_call_arguments.done, y por último response.completed, response.incomplete o response.failed con el objeto response completo. Cada evento lleva sequence_number. Si el proveedor falla se envía un evento error.
const stream = await client.responses.create({ model: "auto", input: "Hola", stream: true });for await (const event of stream) { if (event.type === "response.output_text.delta") process.stdout.write(event.delta); if (event.type === "response.completed") console.log("\n", event.response.conversation.id, event.response.zabio);}Búsqueda web
Section titled “Búsqueda web”Envía tools: [{"type": "web_search"}] y el propio proveedor del modelo busca en la web para el turno: la búsqueda web de Anthropic en un modelo Claude, la de OpenAI en un modelo de OpenAI. El modelo decide si busca y qué busca. tool_choice: {"type": "web_search"}, o required sin ninguna herramienta de función, hace que un modelo de OpenAI busque antes de responder; en un modelo Claude la decisión sigue siendo del modelo.
const response = await client.responses.create({ model: "claude-sonnet-5", input: "¿Cuál es la última versión estable de Go? Cita la fuente.", tools: [{ type: "web_search" }],});Funciona en un modelo nombrado en model cuyo zabio.pricing.per_search aparece en GET /v1/models. auto todavía no busca, y tampoco los modelos de los demás proveedores: una petición así responde 400 unsupported_for_model.
| Campo | |
|---|---|
tools[].search_context_size |
low, medium o high en modelos de OpenAI. Los modelos Claude no tienen ese ajuste, así que allí aparece en zabio.ignored_parameters |
tools[].user_location |
{"type": "approximate", "country", "city", "region", "timezone"} |
tools[].filters |
allowed_domains y blocked_domains, hasta 100 cada una. Un modelo Claude acepta una de las dos, no ambas |
max_tool_calls, zabio.search.max_uses |
el máximo de búsquedas que el turno puede hacer, de 1 a 100, 3 si no se envía ninguno; zabio.search.max_uses gana cuando van los dos |
include: ["web_search_call.action.sources"] |
lista las direcciones que devolvió cada búsqueda en el action.sources de la búsqueda |
La respuesta lleva un elemento de salida web_search_call por búsqueda, antes del mensaje (id, status y action con su type y su query), y el output_text del mensaje lleva annotations de tipo url_citation (url, title, start_index, end_index, contados en caracteres del texto). En streaming los eventos son los de OpenAI: response.web_search_call.in_progress, response.web_search_call.searching y response.web_search_call.completed por cada búsqueda, y response.output_text.annotation.added por cada cita.
Cada búsqueda que el proveedor cuenta se factura en su propia línea junto a la llamada, al precio por búsqueda del proveedor con la comisión de Zabio. zabio.search dice quién buscó (engine), cuántas búsquedas contó el proveedor (searches), el máximo que el turno podía hacer (max_uses) y lo que costaron (cost_micros); zabio.cost.search_micros y zabio.cost.search_fee_micros son las dos partes de esa línea, y zabio.cost_micros la incluye. La cabecera x-zabio-searches lleva el número en una respuesta sin streaming. Los resultados cuentan como tokens de entrada de la llamada, como los cuenta el proveedor. Una petición aparta del saldo el coste de sus búsquedas al ser admitida, así que un saldo que no las cubre responde 402 antes de que se haga ninguna búsqueda.
Lo que no busca:
- un turno en
backgroundy una línea de un lote (400unsupported_parameter) - una llamada con la key de OpenAI propia de tu organización (400
unsupported_for_model): la búsqueda de OpenAI solo funciona con la key de OpenAI de Zabio. Un modelo Claude con tu propia key de Anthropic sí busca, y Anthropic te cobra las búsquedas directamente - una key con la búsqueda web desactivada (403
web_search_disabled), y una llamada dentro de los límites del plan Free (402insufficient_credits) - en modelos de OpenAI, una petición con
stop, con un límite de salida inferior a 16 tokens, o con audio o vídeo web_search_previewyexternal_web_access: false: envíaweb_search
Una conversación guardada conserva las búsquedas (sus consultas y su estado) y las citas (dirección y título), nunca el texto de los resultados, que solo tiene el proveedor. El modelo de un turno posterior lee la respuesta anterior, no la búsqueda anterior.
El proveedor hace la búsqueda y lee las páginas. Zabio no ve ni revisa los resultados, así que trata lo que dice una página citada como contenido no fiable.
Errores propios de este endpoint
Section titled “Errores propios de este endpoint”| Estado | code | Cuándo |
|---|---|---|
| 400 | invalid_value en background |
background con stream, o con store: false |
| 400 | background_unavailable |
las responses en segundo plano no están disponibles en este servidor |
| 400 | not_background |
cancelar una response que no se creó con background |
| 409 | not_cancellable |
cancelar un turno ya enviado al proveedor del modelo dentro de un lote; la respuesta llega y se factura |
| 400 | conversation_mismatch |
previous_response_id pertenece a otra conversación |
| 400 | conversation_too_large |
la conversación llegó a 4,000 entradas o 2,000,000 de tokens estimados en su hilo; empieza una nueva |
| 400 | context_length_exceeded |
el historial más este turno no cabe en la ventana de contexto del modelo y la compactación está desactivada o no puede ayudar; el mensaje incluye las cifras |
| 403 | conversations_closed |
las conversaciones guardadas están cerradas para esta organización |
| 404 | previous_response_not_found, conversation_not_found, response_not_found |
desconocida o borrada |
| 503 | conversations_unavailable |
las conversaciones guardadas no están disponibles en este servidor |
También aplica todo lo de Errores, incluido el 402 insufficient_credits y los códigos free_tier_* del plan Free.
Leer y borrar responses
Section titled “Leer y borrar responses”GET /v1/responses/{id}devuelve una response guardada con su salida, o su estado actual si es una response en segundo plano que todavía se ejecuta.POST /v1/responses/{id}/cancelcancela una response en segundo plano.DELETE /v1/responses/{id}elimina la response con su turno (las entradas que guardó y las salidas) y todo lo guardado después en el mismo hilo. La conversación continúa desde donde empezaba ese turno. Borrar una response en segundo plano en cola la saca de la cola.
Conversaciones
Section titled “Conversaciones”POST /v1/conversationscon{"metadata": {...}, "items": [...], "zabio": {"retention_days": 30}}crea una conversación vacía (o con contenido inicial).GET /v1/conversations/{id}devuelve{"id", "object": "conversation", "created_at", "metadata", "zabio": {"entries", "token_estimate", "expires_at", "last_turn_at", "retention_days", "leaf_id"}}.leaf_ides el id del último item del hilo propio de la conversación (null mientras está vacía).POST /v1/conversations/{id}con{"metadata": {...}}sustituye los metadatos.DELETE /v1/conversations/{id}borra la conversación y todo lo que contiene, de forma inmediata y permanente.GET /v1/conversations/{id}/items?limit=20&after=msg_...&order=asclista todos los items guardados en orden de creación (todos los hilos), incluidos los resúmenes de compactación como{"type": "compaction", "summary": ...}. Cada item llevazabio: {"parent_id", "response_id"}: el item anterior en su hilo y la respuesta que lo guardó (cada uno null cuando no hay), para que puedas reconstruir un hilo: desdeleaf_idpara el hilo propio de la conversación, o desde el item más reciente para la última rama creada conprevious_response_id.POST /v1/conversations/{id}/itemscon{"items": [...]}añade items sin un turno de modelo, por ejemplo para cargar historial previo.
Qué ve cada key
Section titled “Qué ve cada key”Una key que pertenece a un proyecto solo lee, continúa, cambia y borra las responses y conversaciones creadas con keys de ese proyecto; una key a nivel de la organización llega a toda la organización. Una response o conversación de fuera responde 404 not_found, como si no existiera. El proyecto es aquel en el que está ahora la key que la creó. Consulta Organizaciones, miembros y keys.
Escalado, persistencia y compactación
Section titled “Escalado, persistencia y compactación”En los turnos auto el modelo puede indicar que la tarea supera su capacidad. Zabio repite entonces el mismo turno en el siguiente modelo de la curva, uno que su conocimiento dice que es probablemente mejor, con todo el historial y devuelve esa respuesta; los turnos siguientes se quedan en el modelo más potente. Dentro de una conversación auto clasifica cada mensaje nuevo del usuario y reutiliza esa tarea en los turnos de resultado de herramienta que siguen, hasta que una señal (una racha de llamadas a herramientas fallidas, una pausa larga, una clasificación con poca confianza, una queja del usuario) provoca una nueva elección.
Cuando el historial guardado más un turno nuevo no caben en la ventana de contexto del modelo que sirve la petición, Zabio resume la parte más antigua del historial con un modelo rápido, guarda el resumen como un item de compactación y continúa. La llamada del resumen se ejecuta con la key de Zabio, se factura como cualquier otra y aparece entre las responses de la conversación; por eso un turno que requiere compactación necesita crédito aunque nombre un modelo servido con tu propia key, y con saldo cero se ejecuta con los términos de Free como cualquier llamada auto, o recibe 402 insufficient_credits antes de que se haga ningún resumen cuando la organización está configurada para detenerse. zabio.compaction: "off" lo desactiva; la petición falla entonces con context_length_exceeded y las cifras.
Llamadas largas
Section titled “Llamadas largas”Un modelo puede pensar o escribir durante minutos. 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 la conexión mientras tanto. 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 el objeto response está listo; los analizadores JSON ignoran los espacios. 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 se entrega como el objeto response constatus: "failed"y un objetoerror(code,message), la forma que tiene en cualquier caso una respuesta fallida. - Con streaming. Siempre que no se ha enviado nada durante 15 segundos, antes de
response.createdsi hace falta, Zabio envía una línea de comentario SSE (: ZABIO PROCESSING), que los clientes SSE ignoran. Un fallo llega como un eventoresponse.failedcon el objeto constatus: "failed"y suerror. - 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. Un turno guardado que se cortó queda marcado
failedoincomplete. - Cabeceras en una llamada larga. El
200y sus cabeceras salen antes de la respuesta; el proveedor, el modelo servido y el enrutado están en el campozabiodel objeto.
Las responses llevan la misma cabecera Server-Timing que chat completions, con las mismas etapas; ver Tiempos del servidor.
Retención y borrado
Section titled “Retención y borrado”Cada organización tiene una retención por defecto (30 días, ajustable de 1 a 365 en Ajustes). Una conversación puede fijar un retention_days más corto o más largo (de 0 a 365) al crearse; 0 la borra en cuanto se devuelve la response. El reloj de retención se reinicia en cada turno. Las conversaciones caducadas se borran cada noche. Borrar a través de la API es inmediato y permanente. Los cuerpos se cifran en reposo con una key que pertenece a tu organización; cerrar la organización borra las conversaciones y destruye la key. Un turno guardado conserva sus imágenes y sus clips de audio junto con su texto, para que los turnos siguientes puedan seguir viéndolos y oyéndolos; el listado de elementos muestra el formato y el tamaño de un clip, nunca sus bytes. Como cada turno posterior reenvía los clips guardados, una conversación que contiene uno necesita en cada turno un modelo que acepte audio (auto sigue eligiendo entre ellos; un modelo nombrado sin audio de entrada responde 400 unsupported_for_model), y el límite de audio del modelo (100 MB en los modelos Gemini, 20 MB en los demás, y 20 MB en todos los modelos con background: true) cuenta los clips guardados junto con los nuevos. Las imágenes guardadas se reenvían igual: un modelo nombrado sin visión responde 400 unsupported_for_model en una conversación que contiene una. Un video es la excepción: Zabio nunca guarda uno, así que un turno guardado conserva solo el formato, el tamaño y la duración del video, el listado de items muestra esa referencia, y en los turnos siguientes el modelo recibe en su lugar una nota breve (“A video was attached here…”) en vez del video. Para volver a preguntar por él, adjúntalo de nuevo; un turno posterior sin video nuevo no necesita un modelo con video de entrada. Con store: false no se conserva nada del turno. Consulta Privacidad.
Registro de cuerpos en llamadas sin estado
Section titled “Registro de cuerpos en llamadas sin estado”/v1/chat/completions y /v1/embeddings no guardan nada salvo que la API key tenga activado el registro de cuerpos (un ajuste de la key, desactivado por defecto). Con él activado, la petición y la respuesta de cada llamada se guardan cifradas durante el periodo de retención de la organización, y los propietarios y administradores pueden leerlas desde la aplicación web. El id de la llamada es el id de la response sin el prefijo chatcmpl-, escrito como call_....