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 — instructions 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.io/v1/responses

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	✅	Identificador del modelo, p. ej. `openai/gpt-6.1-sol`
`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 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

cURL

Terminal


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

Python

responses.py


from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.ofox.io/v1",
    api_key="<su OFOXAI_API_KEY>"
)
 
response = client.responses.create(
    model="openai/gpt-6.1-sol",
    input="Explica qué es un API Gateway",
    instructions="Eres un asistente técnico útil, responde en español.",
    max_output_tokens=1024
)
 
print(response.output_text)

TypeScript

responses.ts


import OpenAI from 'openai'
 
const client = new OpenAI({
  baseURL: 'https://api.ofox.io/v1',
  apiKey: '<su OFOXAI_API_KEY>'
})
 
const response = await client.responses.create({
  model: 'openai/gpt-6.1-sol',
  input: 'Explica qué es un API Gateway',
  instructions: 'Eres un asistente técnico útil, responde en español.',
  max_output_tokens: 1024
})
 
console.log(response.output_text)

Formato de respuesta


{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1703123456,
  "model": "openai/gpt-6.1-sol",
  "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

multi_turn.py


response = client.responses.create(
    model="openai/gpt-6.1-sol",
    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.py


stream = client.responses.create(
    model="openai/gpt-6.1-sol",
    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

tools.py


response = client.responses.create(
    model="openai/gpt-6.1-sol",
    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-6.1-sol",
    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.