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 nativo —
instructionseinputestá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/responsesParámetros de solicitud
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model | string | ✅ | Identificador del modelo, p. ej. openai/gpt-5.4-mini |
input | string | array | ✅ | Contenido de entrada, puede ser una cadena de texto simple o un array de mensajes estructurado |
instructions | string | — | Instrucciones del sistema (independientes de input, se benefician automáticamente del Prompt Caching) |
stream | boolean | — | Activar respuesta en streaming SSE, por defecto false |
max_output_tokens | number | — | Número máximo de tokens a generar |
temperature | number | — | Temperatura de muestreo 0-2, por defecto 1 |
top_p | number | — | Parámetro de muestreo nucleus |
tools | array | — | Definición de herramientas disponibles (Function Calling) |
tool_choice | string | object | — | Estrategia de selección de herramientas: auto, none o herramienta específica |
truncation | string | — | Estrategia de truncado: auto truncado automático / disabled error al exceder el límite (por defecto) |
text | object | — | Configuración del formato de generación de texto |
store | boolean | — | Si se almacena la respuesta (por defecto true) |
metadata | object | — | Pares clave-valor de metadatos personalizados |
provider | object | — | Extensió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 asistenteAl 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
cURL
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
| Campo | Tipo | Descripción |
|---|---|---|
id | string | Identificador único de la respuesta, comienza con resp_ |
object | string | Valor fijo "response" |
created_at | number | Marca de tiempo de creación (Unix en segundos) |
model | string | ID del modelo realmente utilizado |
status | string | Estado de la respuesta: completed, failed, in_progress, cancelled |
output | array | Array de items de salida, incluye mensajes y llamadas a herramientas |
usage | object | Estadísticas de uso de tokens |
Entrada de mensajes estructurada
Utilice un array de mensajes estructurado para implementar conversaciones multi-turno:
Python
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:
Python
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 evento | Descripción |
|---|---|
response.created | Objeto de respuesta creado |
response.output_item.added | Nuevo item de salida añadido |
response.content_part.added | Nuevo fragmento de contenido añadido |
response.output_text.delta | Incremento de texto (salida token a token) |
response.output_item.done | Item de salida completado |
response.completed | Respuesta completada en su totalidad |
response.function_call_arguments.delta | Incremento de argumentos de llamada a función |
response.function_call_arguments.done | Argumentos de llamada a función completados |
Function Calling
Responses API soporta de forma nativa la llamada a herramientas:
Python
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
| Valor | Descripció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ística | Chat Completions | Responses API |
|---|---|---|
| Endpoint | /v1/chat/completions | /v1/responses |
| Formato de entrada | Array messages | Cadena input o array de items estructurado |
| Instrucciones del sistema | Mensaje role: "system" | Parámetro instructions (caché independiente) |
| Prompt Caching | Las instrucciones del sistema están mezcladas en messages, el prefijo de caché es inestable | instructions se pasa de forma independiente, se almacena en caché automáticamente con mayor tasa de aciertos |
| Formato de salida | choices[0].message.content | output[0].content[0].text o output_text |
| Llamadas a herramientas | tool_calls dentro del mensaje | Item de salida function_call independiente |
| Resultados de herramientas | Mensaje role: "tool" | Item de entrada function_call_output |
| Eventos de streaming | chat.completion.chunk | Tipos de eventos estructurados (response.*) |
| Campos de tokens | prompt_tokens / completion_tokens | input_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.