Skip to Content
APIProtocolo compatible con OpenAIResponses (Recomendado)

Responses API (Recomendado)

Cree respuestas del modelo. Soporta entradas de texto e imagen y genera salidas de texto o JSON. Soporta llamada a funciones (Tool Calling), respuestas en streaming y conversaciones multi-turno.

Se recomienda usar Responses API para nuevos proyectos. Esta es la nueva generación de API lanzada por OpenAI, y en comparación con Chat Completions ofrece las siguientes ventajas:

  • Prompt Caching nativoinstructions e input están separados, las instrucciones del sistema se utilizan automáticamente como prefijo de caché. En conversaciones multi-turno, la parte de prefijo invariable obtiene una mayor tasa de aciertos de caché, pudiendo ahorrar hasta un 50 % en el coste de los tokens de entrada y reducir la latencia.
  • Modelo de items estructurado — los formatos de entrada/salida son más claros y soportan de forma nativa el flujo de llamada a herramientas.
  • Eventos de streaming más completos — tipos de eventos SSE granulares, ideales para renderizado de UI en tiempo real.

Endpoint

POST https://api.ofox.ai/v1/responses

Parámetros de solicitud

ParámetroTipoObligatorioDescripción
modelstringIdentificador del modelo, p. ej. openai/gpt-5.4-mini
inputstring | arrayContenido de entrada, puede ser una cadena de texto simple o un array de mensajes estructurado
instructionsstringInstrucciones del sistema (independientes de input, se benefician automáticamente del Prompt Caching)
streambooleanActivar respuesta en streaming SSE, por defecto false
max_output_tokensnumberNúmero máximo de tokens a generar
temperaturenumberTemperatura de muestreo 0-2, por defecto 1
top_pnumberParámetro de muestreo nucleus
toolsarrayDefinición de herramientas disponibles (Function Calling)
tool_choicestring | objectEstrategia de selección de herramientas: auto, none o herramienta específica
truncationstringEstrategia de truncado: auto truncado automático / disabled error al exceder el límite (por defecto)
textobjectConfiguración del formato de generación de texto
storebooleanSi se almacena la respuesta (por defecto true)
metadataobjectPares clave-valor de metadatos personalizados
providerobjectExtensión OfoxAI: configuración de enrutamiento y respaldo

Formato de Input

input soporta dos formatos:

1. Cadena simple — pasar texto directamente

{ "input": "Hola, preséntate por favor" }

2. Array de mensajes estructurado — conversación multi-turno y entrada multimodal

interface InputItem { type: 'message' role: 'user' | 'assistant' content: ContentPart[] id?: string // obligatorio para mensajes assistant status?: 'completed' // obligatorio para mensajes assistant } type ContentPart = | { type: 'input_text'; text: string } // entrada de texto del usuario | { type: 'input_image'; image_url: string } // entrada de imagen | { type: 'output_text'; text: string; annotations?: any[] } // salida de texto del asistente

Al incluir mensajes con rol assistant en una conversación multi-turno, los campos id y status son obligatorios. La Responses API está diseñada sin estado, por lo que cada solicitud debe incluir el historial completo de la conversación.

Ejemplo de solicitud

Terminal
curl https://api.ofox.ai/v1/responses \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.4-mini", "input": "Explica qué es un API Gateway", "instructions": "Eres un asistente técnico útil, responde en español.", "max_output_tokens": 1024 }'

Formato de respuesta

{ "id": "resp_abc123", "object": "response", "created_at": 1703123456, "model": "openai/gpt-5.4-mini", "status": "completed", "output": [ { "type": "message", "id": "msg_def456", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "Un API Gateway (puerta de enlace de API) es un...", "annotations": [] } ] } ], "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 } }

Descripción de los campos de respuesta

CampoTipoDescripción
idstringIdentificador único de la respuesta, comienza con resp_
objectstringValor fijo "response"
created_atnumberMarca de tiempo de creación (Unix en segundos)
modelstringID del modelo realmente utilizado
statusstringEstado de la respuesta: completed, failed, in_progress, cancelled
outputarrayArray de items de salida, incluye mensajes y llamadas a herramientas
usageobjectEstadísticas de uso de tokens

Entrada de mensajes estructurada

Utilice un array de mensajes estructurado para implementar conversaciones multi-turno:

multi_turn.py
response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "¿Cuál es la capital de Francia?"} ] }, { "type": "message", "role": "assistant", "id": "msg_abc123", "status": "completed", "content": [ {"type": "output_text", "text": "La capital de Francia es París.", "annotations": []} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "¿Cuántos habitantes tiene?"} ] } ] ) print(response.output_text)

Respuesta en streaming

Establezca stream: true para activar la respuesta en streaming SSE:

stream.py
stream = client.responses.create( model="openai/gpt-5.4-mini", input="Cuéntame un chiste sobre programación", stream=True ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True)

Tipos de eventos de streaming

La respuesta en streaming envía los siguientes eventos mediante SSE:

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}} data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}} data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Ho"} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"la"} data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Hola..."}]}} data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}} data: [DONE]
Tipo de eventoDescripción
response.createdObjeto de respuesta creado
response.output_item.addedNuevo item de salida añadido
response.content_part.addedNuevo fragmento de contenido añadido
response.output_text.deltaIncremento de texto (salida token a token)
response.output_item.doneItem de salida completado
response.completedRespuesta completada en su totalidad
response.function_call_arguments.deltaIncremento de argumentos de llamada a función
response.function_call_arguments.doneArgumentos de llamada a función completados

Function Calling

Responses API soporta de forma nativa la llamada a herramientas:

tools.py
response = client.responses.create( model="openai/gpt-5.4-mini", input="¿Qué tiempo hace hoy en Madrid?", tools=[ { "type": "function", "name": "get_weather", "description": "Obtiene el tiempo actual de una ciudad especificada", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "Nombre de la ciudad, p. ej. Madrid" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } ], tool_choice="auto" ) # Procesar llamadas a herramientas for item in response.output: if item.type == "function_call": print(f"Llamada a función: {item.name}") print(f"Argumentos: {item.arguments}")

Formato de respuesta de llamada a herramientas

Cuando el modelo llama a una herramienta, output contiene un item de tipo function_call:

{ "id": "resp_abc123", "object": "response", "status": "completed", "output": [ { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"Madrid\",\"unit\":\"celsius\"}" } ], "usage": { "input_tokens": 45, "output_tokens": 25, "total_tokens": 70 } }

Envío de resultados de herramientas

Devuelva el resultado de ejecución de la herramienta al modelo, incluyendo la cadena de llamadas completa en input:

# Segunda solicitud: enviar el resultado de la herramienta response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "¿Qué tiempo hace hoy en Madrid?"}] }, { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"Madrid\",\"unit\":\"celsius\"}" }, { "type": "function_call_output", "id": "fco_abc123", "call_id": "call_xyz789", "output": "{\"temperature\":\"22°C\",\"condition\":\"soleado\"}" } ] ) print(response.output_text) # => "Hoy en Madrid hace sol, con una temperatura de 22 °C, perfecto para actividades al aire libre."

Opciones de Tool Choice

ValorDescripción
"auto"El modelo decide por sí mismo si llamar a una herramienta (por defecto)
"none"Prohíbe llamar a herramientas
{"type": "function", "name": "tool_name"}Fuerza la llamada a la herramienta especificada

Comparación con Chat Completions

CaracterísticaChat CompletionsResponses API
Endpoint/v1/chat/completions/v1/responses
Formato de entradaArray messagesCadena input o array de items estructurado
Instrucciones del sistemaMensaje role: "system"Parámetro instructions (caché independiente)
Prompt CachingLas instrucciones del sistema están mezcladas en messages, el prefijo de caché es inestableinstructions se pasa de forma independiente, se almacena en caché automáticamente con mayor tasa de aciertos
Formato de salidachoices[0].message.contentoutput[0].content[0].text o output_text
Llamadas a herramientastool_calls dentro del mensajeItem de salida function_call independiente
Resultados de herramientasMensaje role: "tool"Item de entrada function_call_output
Eventos de streamingchat.completion.chunkTipos de eventos estructurados (response.*)
Campos de tokensprompt_tokens / completion_tokensinput_tokens / output_tokens

Ambas API son aptas para producción. Si ya tiene una integración con Chat Completions, no es necesario migrar. Se recomienda usar Responses API para nuevos proyectos, especialmente en escenarios que requieren flujos complejos de llamada a herramientas o llamadas de alta frecuencia (donde se puede aprovechar al máximo la caché para reducir costes). Consulte la guía de llamada a funciones.

Last updated on