API de respuestas de OpenAI: La guía definitiva para desarrolladores

¿Qué es la API de respuestas de OpenAI?

La API de respuestas es la API más nueva y avanzada de OpenAI. Combina los puntos fuertes de las API de Finalización del Chat y Asistentes en una única interfaz racionalizada. Lanzado en marzo de 2025, mantiene las capacidades conocidas al tiempo que proporciona un enfoque más integrado para crear aplicaciones de IA. 

La innovación clave es cómo simplifica el desarrollo gestionando automáticamente la lógica de orquestación e integrando de forma nativa las herramientas incorporadas de OpenAI para la búsqueda web y de archivos, sin necesidad de una implementación personalizada.

En este tutorial, veremos cómo utilizar la API de respuestas en tus proyectos. Verás cómo gestiona la generación de texto, trabaja con imágenes y ofrece respuestas en streaming. Examinaremos las herramientas integradas que hacen que el desarrollo sea más rápido y sencillo que antes, mostrándote cómo estas herramientas funcionan juntas dentro del marco de la API. 

Al final de esta guía, entenderás cuándo utilizar la API de Respuestas en lugar de otras opciones de OpenAI y cómo este conocimiento puede ayudarte a crear aplicaciones más eficientes con menos código y esfuerzo. Si eres nuevo en la API OpenAI, consulta nuestro curso introductorio, Trabajar con la API OpenAIpara empezar a desarrollar aplicaciones basadas en IA.

Primeros pasos con la API de respuestas

La API de respuestas proporciona una interfaz más ágil y fácil de usar para interactuar con los modelos de OpenAI, combinando en una solución elegante lo que antes requería una sintaxis verborreica y compleja. 

Antes de sumergirnos en casos de uso concretos, vamos a configurar nuestro entorno y a comprender la sintaxis básica.

from openai import OpenAI
import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Initialize the client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Este paso de inicialización crea un objeto cliente que gestionará todas tus peticiones a la API. El paquete dotenv ayuda a gestionar tu clave API de forma segura a través de variables de entorno, en lugar de codificarla en tu script: una práctica recomendada que hace que tu código sea más portátil y seguro en distintos entornos.

Generar contenido con la API de respuestas

El uso más sencillo de la API Respuestas es generar contenido de texto. Exploremos un escenario del mundo real: supongamos que estás construyendo una plataforma de comercio electrónico y necesitas generar automáticamente descripciones de producto convincentes a partir de los detalles básicos del producto.

Tradicionalmente, esto requeriría una cuidadosa ingeniería rápida y múltiples iteraciones. Con la API de Respuestas, puedes crear una función sencilla que se encargue de esto con elegancia:

def generate_product_description(product_name, features, target_audience):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a professional copywriter specialized in creating concise, compelling product descriptions. Focus on benefits rather than just features.",
       input=f"""
       Create a product description for {product_name}.
       Key features:
       - {features[0]}
       - {features[1]}
       - {features[2]}
       Target audience: {target_audience}
       Keep it under 150 words.
       """,
       temperature=0.7,
       max_output_tokens=200
   )
  
   return response.output_text

# Example usage
headphones_desc = generate_product_description(
   "NoiseGuard Pro Headphones",
   ["Active noise cancellation", "40-hour battery life", "Memory foam ear cushions"],
   "Business travelers and remote workers"
)

print(headphones_desc)

Salida:

Experience unparalleled focus and comfort with NoiseGuard Pro Headphones—your perfect travel and work companion. 
Designed for business travelers and remote workers, these headphones feature cutting-edge active noise cancellation to block out distractions, allowing you to concentrate on what truly matters. 
With an impressive 40-hour battery life, you can enjoy uninterrupted productivity or relaxation on even the longest journeys. 
The luxurious memory foam ear cushions ensure a snug, comfortable fit for all-day wear, reducing fatigue and enhancing your listening experience. 
Elevate your work and travel with NoiseGuard Pro—where clarity meets comfort.

Con unas pocas líneas de código, hemos creado textos de calidad comercial que normalmente requerirían un redactor profesional. La función también es reutilizable: sólo tienes que cambiar los parámetros y podrás generar descripciones para cualquier producto de tu catálogo.

Este ejemplo demuestra patrones clave al utilizar la API de Respuestas:

1. El parámetro instructions actúa como un indicador del sistema, definiendo el comportamiento y el contexto de la IA.
2. El parámetro temperature (0-2) controla la aleatoriedad: los valores más bajos producen resultados más deterministas, mientras que los valores más altos introducen más creatividad.
3. El parámetro max_output_tokens limita la longitud de la respuesta, lo que ayuda a controlar los costes y a garantizar resultados concisos.
4. El objeto respuesta contiene el texto generado en la propiedad output_text.

Análisis de imágenes para aplicaciones prácticas

Muchas aplicaciones del mundo real necesitan procesar tanto texto como imágenes. Por ejemplo, las plataformas de comercio electrónico necesitan analizar las fotos de los productos, los sistemas de moderación de contenidos necesitan revisar las cargas, y las aplicaciones de redes sociales necesitan comprender el contenido visual.

La API Respuestas destaca en tareas multimodales como el análisis de imágenes, sin necesidad de puntos finales separados ni de código de integración complejo:

def analyze_product_image(image_url):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a product photography expert and e-commerce consultant.",
       input=[
           {"role": "user", "content": "Analyze this product image and provide the following details:\n1. Product category\n2. Key visible features\n3. Potential quality issues\n4. Suggested improvements for the product photography"},
           {
               "role": "user",
               "content": [
                   {
                       "type": "input_image",
                       "image_url": image_url
                   }
               ],
           },
       ],
       temperature=0.2
   )
  
   return response.output_text

# Example with a sports team image
analysis = analyze_product_image("https://upload.wikimedia.org/wikipedia/commons/a/a5/Barcelona_fc_lamina_elgrafico.jpg")
print(analysis)

Salida:

1. **Product Category**: Sports team memorabilia or vintage sports photography.

2. **Key Visible Features**:
  - The image features a group of individuals in sports uniforms, likely a football (soccer) team.
  - The uniforms have distinct vertical stripes in red and blue.
  - A football is visible in the foreground.
  - The setting appears to be an outdoor field, possibly a stadium.

...

Esta función podría integrarse en una plataforma de comercio electrónico para analizar automáticamente las fotos de los productos cuando los comerciantes las suban. El sistema podría proporcionar información inmediata sobre la calidad de la imagen y sugerir mejoras, lo que en última instancia conduciría a mejores tasas de conversión mediante anuncios de mayor calidad, todo ello sin revisión manual.

Cuando trabajes con imágenes, debes pasar una matriz de objetos mensaje al parámetro de entrada en lugar de una cadena, cada uno con un rol y valores de contenido.

 El contenido de la imagen se especifica como un objeto con type: input_image y un image_url. Puedes combinar texto e imágenes en la misma solicitud, lo que permite interacciones multimodales enriquecidas.

Implementar el streaming para aplicaciones responsivas

Los usuarios esperan una respuesta instantánea. Esperar varios segundos a una respuesta de la IA puede acabar con el compromiso: por eso el streaming es esencial para crear experiencias de usuario receptivas, especialmente en aplicaciones de chat o en tiempo real.

Imagina que estás creando una herramienta de análisis de las opiniones de los clientes para un equipo de producto. En lugar de hacerles esperar al análisis completo, puedes transmitir los resultados a medida que se generan:

def analyze_customer_feedback(feedback_text):
   print("Analyzing customer feedback in real-time:")
  
   stream = client.responses.create(
       model="gpt-4o",
       instructions="Extract key sentiments, product issues, and actionable insights from this feedback.",
       input=feedback_text,
       stream=True,
       temperature=0.3,
       max_output_tokens=500
   )
  
   full_response = ""
   print("\nAnalysis results:")
   for event in stream:
       if event.type == "response.output_text.delta":
           print(event.delta, end="")
           full_response += event.delta
       elif event.type == "response.error":
           print(f"\nError occurred: {event.error}")
  
   return full_response

# Example with a complex customer review
feedback = """
I've been using the SmartHome Hub for about 3 months now. The voice recognition is fantastic
and the integration with my existing devices was mostly seamless. However, the app crashes
at least once a day, and the night mode feature often gets stuck until I restart the system.
Customer support was helpful but couldn't fully resolve the app stability issues.
"""

analysis_result = analyze_customer_feedback(feedback)

En una aplicación real, sustituirías las afirmaciones de print por actualizaciones de la interfaz de usuario, lo que permitiría a tus usuarios ver cómo se forma el análisis en tiempo real, de forma parecida a como las modernas aplicaciones de chat muestran a la IA "pensando" mientras genera una respuesta. Esto crea una experiencia más atractiva y proporciona a los usuarios información inmediata de que su solicitud está siendo procesada.

La implementación del streaming funciona de la siguiente manera

1. Establecer stream=True en el método crear
2. Procesar la respuesta como una iterable de eventos con tipos específicos
3. Gestión de distintos tipos de eventos por separado: response.output_text.delta para los trozos de contenido, response.error para los errores

Ahora que hemos cubierto la funcionalidad básica de la API Respuestas, vamos a explorar sus herramientas integradas que mejoran aún más sus capacidades.

Herramientas integradas en la API de respuestas de OpenAI

La API Respuestas integra unas cuantas herramientas incorporadas que amplían sus capacidades más allá de la generación básica de texto. Estas herramientas permiten a los desarrolladores crear aplicaciones más potentes sin necesidad de complejos códigos de integración o múltiples llamadas a la API.

Búsqueda web: acceso a la información en tiempo real

La herramienta de búsqueda en la web permite a la API de Respuestas recuperar información actual de Internet, abordando la limitación de que los LLM estén restringidos a sus datos de entrenamiento.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
   model="gpt-4o",
   tools=[{"type": "web_search_preview"}],
   input="What are some news related to the stock market?",
)

print(response.output_text)

Salida:

Recent developments in the stock market have been significantly influenced by escalating trade tensions between the United States and China. On April 5, 2025, President Donald Trump announced an additional 34% tariff on Chinese goods, raising total tariffs to 54% this year. In response, China imposed reciprocal 34% tariffs on U.S. products and introduced export restrictions on certain rare earth elements. These actions led to a sharp global market selloff, with the S&P 500 falling 9% for the week, marking the steepest decline since the pandemic. (reuters.com)

…..


## Escalating US-China Trade Tensions Impact Global Markets:
- [China says 'market has spoken' after US tariffs spark selloff](https://www.reuters.com/world/china/china-says-market-has-spoken-after-us-tariffs-spark-selloff-2025-04-05/?utm_source=openai)
- [Trump touts "economic revolution" as economists warn of recession](https://www.axios.com/2025/04/05/trump-tariffs-stock-market-recession?utm_source=openai)
- [Believe it or not, there were some winners in the stock market this week](https://apnews.com/article/ce81e9ae6fb463dc763dfaa464778343?utm_source=openai)

La herramienta de búsqueda web realiza varias operaciones cuando se activa, desde analizar la consulta hasta sintetizar la información de múltiples fuentes con las citas adecuadas. Esta capacidad abre posibilidades para aplicaciones ricas en información, como herramientas de análisis financiero que proporcionen perspectivas de mercado, plataformas de agregación de noticias que combinen múltiples fuentes o recursos educativos que complementen los contenidos básicos con investigaciones actuales.

Una ventaja clave de esta herramienta es la capacidad de proporcionar información puntual sin necesidad de crear y mantener una integración de búsqueda personalizada o un sistema de raspado web. La herramienta gestiona el proceso de búsqueda al tiempo que presenta los resultados con citas adecuadas para mantener la transparencia sobre las fuentes de información.

Búsqueda de archivos: extraer información de los documentos

Mientras que la búsqueda web aporta conocimientos externos a tu aplicación, la herramienta de búsqueda de archivos se centra en desbloquear la información de los documentos. Esta herramienta permite a la API buscar y extraer información de los documentos que se han subido a OpenAI.

La herramienta de búsqueda de archivos permite varias funciones clave:

• Búsqueda en varios tipos de archivos (PDF, documentos de Word, presentaciones, etc.).
• Encontrar información específica dentro de los documentos a partir de consultas en lenguaje natural.
• Extraer y sintetizar información de varios documentos simultáneamente.
• Proporcionar citas a secciones específicas de los documentos fuente.
• Apoyar consultas complejas que hagan referencia a información de varios archivos.

Esta capacidad es muy adecuada para casos de uso de análisis de documentos, como extraer información de contratos legales, analizar trabajos de investigación o construir bases de conocimiento a partir de documentación técnica. La herramienta puede identificar secciones relevantes en múltiples documentos y sintetizar información en respuesta a consultas específicas.

La implementación requiere primero subir archivos al punto final de archivos de OpenAI, y luego pasar los ID de archivo a la API de Respuestas al hacer una consulta. Esto crea un flujo de trabajo optimizado para las aplicaciones que necesitan hacer referencia a información específica dentro de los documentos sin que los usuarios tengan que buscar manualmente.

Uso del ordenador: capacidades de interacción de la interfaz

Partiendo de la base de la comprensión de textos y documentos, la herramienta de uso informático amplía las capacidades de la IA al ámbito de la interacción de interfaces. Esta herramienta representa un avance significativo que tiende un puente entre la comprensión del lenguaje y la manipulación de la interfaz de usuario.

La herramienta de uso del ordenador puede realizar diversas interacciones con la interfaz:

• Navega por sitios y aplicaciones web de forma autónoma.
• Rellena los formularios con la información adecuada.
• Extrae datos de páginas web y aplicaciones.
• Ejecuta procesos de varios pasos en diferentes pantallas.
• Interactúa con elementos como botones, desplegables y campos de texto.
• Comprender el contexto y la finalidad de los distintos elementos de la interfaz.

Las aplicaciones potenciales incluyen la automatización de procesos para tareas repetitivas, asistencia guiada para flujos de trabajo complejos y mejoras de accesibilidad para usuarios que tienen dificultades con las interfaces tradicionales. La herramienta podría utilizarse para automatizar el rellenado de formularios, navegar por sitios web complejos o realizar pruebas de interfaces de usuario.

La tecnología funciona permitiendo a la IA ver e interactuar con los elementos de la pantalla, comprender el contexto y ejecutar acciones basadas en instrucciones de lenguaje natural. Esto crea posibilidades de automatización y asistencia que, de otro modo, requerirían el desarrollo especializado de código específico para la interfaz.

Funciones adicionales de la herramienta

El ecosistema de herramientas de la API de Respuestas sigue creciendo, y OpenAI añade regularmente nuevas capacidades. La completa documentación sobre herramientas cubre los detalles de aplicación de todas las herramientas disponibles en la actualidad, mientras que el artículo sobre nuevas herramientas para construir agentes proporciona un contexto estratégico sobre cómo están evolucionando estas herramientas.

Estas herramientas integradas proporcionan potentes capacidades listas para usar, pero muchas aplicaciones requieren conectarse a servicios especializados o sistemas propietarios. Aquí es donde la llamada a funciones resulta esencial, ya que te permite ampliar la API Respuestas con tus propias herramientas personalizadas y servicios externos, que serán el tema central de nuestra próxima sección.

Llamada a funciones en la API de respuestas

Aunque las herramientas integradas proporcionan potentes capacidades, muchas aplicaciones requieren conectarse a servicios especializados o sistemas propietarios. La llamada a funciones te permite ampliar la API de respuestas con tus propias herramientas personalizadas, permitiendo que el modelo determine cuándo y cómo llamar a tus funciones en función de la entrada del usuario.

La llamada a funciones crea un puente entre la comprensión lingüística de la IA y tus sistemas externos, ya sea para recuperar tipos de cambio, calcular distancias o comprobar la disponibilidad de citas. Este patrón sigue un flujo de trabajo claro:

1. Defines las funciones que puede utilizar la IA, especificando los parámetros y sus tipos.
2. La IA decide cuándo llamar a estas funciones basándose en las consultas del usuario.
3. Tu código ejecuta las funciones con los parámetros proporcionados por la IA.
4. Devuelves los resultados a la IA, que los incorpora a su respuesta.

Crear una herramienta de conversión de divisas

Pongamos como ejemplo una sencilla función de conversión de moneda:

# Dictionary of exchange rates (relative to USD)
exchange_rates = {
   "USD": 1.0,
   "EUR": 0.93,
   "GBP": 0.79,
   "JPY": 153.2,
   "CAD": 1.37,
   "AUD": 1.52
}

def convert_currency(amount, from_currency, to_currency):
   """Convert an amount from one currency to another."""
   # Normalize currency codes to uppercase
   from_currency = from_currency.upper()
   to_currency = to_currency.upper()
  
   # Check if currencies are supported
   if from_currency not in exchange_rates:
       return {"error": f"Currency not supported: {from_currency}"}
   if to_currency not in exchange_rates:
       return {"error": f"Currency not supported: {to_currency}"}
  
   # Convert to USD first, then to target currency
   amount_in_usd = amount / exchange_rates[from_currency]
   converted_amount = amount_in_usd * exchange_rates[to_currency]
  
   return {
       "original_amount": amount,
       "from_currency": from_currency,
       "to_currency": to_currency,
       "converted_amount": round(converted_amount, 2)
   }

Esta función toma tres parámetros: la cantidad a convertir, la moneda de origen y la moneda de destino. Realiza una conversión sencilla utilizando tipos de cambio predefinidos y devuelve un resultado estructurado con los detalles de la conversión.

Definir la función para la API de respuestas

Ahora, tenemos que informar al modelo sobre nuestra función para que pueda decidir cuándo llamarla:

from openai import OpenAI
import json

client = OpenAI()

tools = [
   {
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }
]

Esta definición especifica claramente:

• El nombre de la función convert_currency que coincide con nuestra función Python.
• Una descripción que explique cuándo debe utilizarse la función.
• Tres parámetros obligatorios con sus tipos y descripciones.
• La bandera strict: true para garantizar que el modelo sigue exactamente nuestras especificaciones de parámetros.

Manejar una consulta de usuario

Vamos a simular una conversación en la que un usuario pregunta por la conversión de divisas:

input_messages = [
   {"role": "user", "content": "How much is 100 euros in Japanese yen?"}
]

response = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)

Cuando el modelo ve esta pregunta sobre la conversión de moneda, reconoce que debe utilizar nuestra función. Lo identifica automáticamente:

• El importe es 100
• La moneda de origen es el euro (EUR)
• La moneda objetivo es el yen japonés (JPY)

Procesar la llamada a la función

Ahora extraemos los detalles de la llamada a la función y ejecutamos nuestra función:

tool_call = response.output[0]
print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")

args = json.loads(tool_call.arguments)

# Execute the function with the parameters determined by the model
conversion_result = convert_currency(**args)
print(f"Function results: {conversion_result}")

El modelo ha traducido la consulta en lenguaje natural a parámetros estructurados. A continuación, nuestra función realiza el cálculo basándose en estos parámetros y devuelve el importe convertido.

Devolver los resultados de la función al modelo

Por último, devolvemos los resultados al modelo para que pueda generar una respuesta fácil de utilizar:

input_messages.append(tool_call)  # append model's function call message
input_messages.append(
   {  # append result message
       "type": "function_call_output",
       "call_id": tool_call.call_id,
       "output": json.dumps(conversion_result)
   }
)

response_2 = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)
print(response_2.output_text)

Salida:

100 euros is equal to 16,473.12 Japanese yen based on current exchange rates.

El modelo ha tomado nuestros datos brutos de conversión y los ha transformado en una respuesta natural, legible por humanos. Interpreta correctamente el resultado numérico y preséntalo en un formato adecuado para la moneda.

Ponerlo todo junto

En una aplicación real, querrás encapsular todo este proceso en una única interfaz que maneje el flujo de la conversación sin problemas. He aquí cómo podrías crear un asistente completo que gestione todo el proceso de llamada a funciones:

def currency_assistant(user_message, conversation_history=None):
   """A complete assistant that handles currency conversion queries."""
   if conversation_history is None:
       conversation_history = []
  
   # Add the user's new message to the conversation
   conversation_history.append({"role": "user", "content": user_message})
  
   # Define available tools (our currency conversion function)
   tools = [{
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }]
  
   # Get initial response from the model
   response = client.responses.create(
       model="gpt-4o",
       input=conversation_history,
       tools=tools,
   )
  
   # Check if the model wants to call a function
   if response.output and isinstance(response.output, list) and response.output[0].type == "function_call":
       tool_call = response.output[0]
      
       # Process the function call
       args = json.loads(tool_call.arguments)
       result = convert_currency(**args)
      
       # Add the function call and its result to the conversation
       conversation_history.append(tool_call)
       conversation_history.append({
           "type": "function_call_output",
           "call_id": tool_call.call_id,
           "output": json.dumps(result)
       })
      
       # Get the final response with the function results incorporated
       final_response = client.responses.create(
           model="gpt-4o",
           input=conversation_history,
           tools=tools,
       )
      
       return final_response.output_text, conversation_history
   else:
       # If no function call was needed, return the direct response
       return response.output_text, conversation_history

# Example usage
response, conversation = currency_assistant("How much is 50 British pounds in Australian dollars?")
print("Assistant:", response)

# Continue the conversation
response, conversation = currency_assistant("And what if I wanted to convert 200 Canadian dollars instead?", conversation)
print("Assistant:", response)

Esta aplicación:

1. Mantiene el historial de la conversación para proporcionar contexto a las preguntas de seguimiento.
2. Maneja todo el proceso de llamada a funciones en una única interfaz.
3. Determina cuándo es necesario llamar a una función y cuándo el modelo puede responder directamente.
4. Admite conversaciones multiturno en las que importa el contexto previo.

Con este enfoque, puedes crear experiencias conversacionales fluidas en las que los usuarios interactúen de forma natural sin ser conscientes de las complejas llamadas a funciones que se producen entre bastidores. El asistente se encarga de la transición entre la comprensión del lenguaje natural, las llamadas a funciones estructuradas y la generación de lenguaje natural.

Construir aplicaciones más complejas puede implicar

1. Admite múltiples funciones, cada una para distintos tipos de consultas.
2. Gestionar la autenticación y autorización para operaciones sensibles.
3. Implementar un tratamiento de errores y una recuperación más sofisticados.
4. Añadir registro y supervisión del uso y rendimiento de las funciones.
5. Crear interfaces de usuario que admitan interacciones de texto, voz o multimodales.

La llamada a funciones permite que la API Respuestas conecte entradas de lenguaje natural con tus servicios y datos. Esto crea un puente entre las peticiones de los usuarios y tus sistemas empresariales, permitiendo a los usuarios hacer peticiones en lenguaje sencillo mientras tu aplicación se encarga de los detalles técnicos de implementación en segundo plano.

Más allá de la llamada a funciones, otra potente capacidad de la API Respuestas es la posibilidad de generar salidas estructuradas. Esta función complementa la llamada a funciones proporcionando una forma de recibir respuestas en formatos específicos que se ajusten a las necesidades de tu aplicación.

Salidas estructuradas con la API Respuestas

Al crear aplicaciones de IA, a menudo necesitas respuestas en un formato específico para facilitar la integración con tus sistemas. La API de respuestas admite salidas estructuradas que te permiten recibir datos en un formato bien definido y coherente, en lugar de texto sin formato. Esta función es especialmente valiosa cuando necesitas

1. Extrae información específica de un texto no estructurado.
2. Transforma las entradas del usuario en datos estructurados.
3. Garantizar formatos de respuesta coherentes para el procesamiento posterior.
4. Integra los resultados de la IA directamente con bases de datos o API.

Las salidas estructuradas reducen la necesidad de análisis sintáctico y validación adicionales, lo que hace que tus aplicaciones sean más robustas y fáciles de mantener.

Extraer información del producto de las descripciones

Exploremos un ejemplo práctico: imagina que estás construyendo una plataforma de comercio electrónico y necesitas extraer automáticamente los detalles de los productos a partir de descripciones de productos no estructuradas para rellenar tu base de datos.

from openai import OpenAI
import json

client = OpenAI()

product_description = """
Our Premium Laptop Backpack is perfect for professionals and students alike.
Made with water-resistant material, it features padded compartments that fit
laptops up to 15.6 inches. The backpack includes 3 main storage areas,
5 smaller pockets, and has an integrated USB charging port. Available in
navy blue, black, and gray. Current retail price: $79.99, though it's
currently on sale for $64.99 until the end of the month.
"""

response = client.responses.create(
   model="gpt-4o",
   input=f"Extract structured product information from this description: {product_description}",
   text={
       "format": {
           "type": "json_schema",
           "name": "product_details",
           "schema": {
               "type": "object",
               "properties": {
                   "product_name": {"type": "string"},
                   "category": {"type": "string"},
                   "features": {"type": "array", "items": {"type": "string"}},
                   "colors": {"type": "array", "items": {"type": "string"}},
                   "pricing": {
                       "type": "object",
                       "properties": {
                           "regular_price": {"type": "number"},
                           "sale_price": {"type": "number"},
                           "currency": {"type": "string"},
                       },
                       "additionalProperties": False,
                       "required": ["regular_price", "sale_price", "currency"],
                   },
               },
               "required": ["product_name", "features", "colors", "pricing","category"],
               "additionalProperties": False,
           },
           "strict": True,
       }
   },
)

product_data = json.loads(response.output_text)
print(json.dumps(product_data, indent=2))

Salida:

{
 "product_name": "Premium Laptop Backpack",
 "category": "Backpack",
 "features": [
   "Water-resistant material",
   "Padded compartments for laptops up to 15.6 inches",
   "3 main storage areas",
   "5 smaller pockets",
   "Integrated USB charging port"
 ],
 "colors": [
   "Navy blue",
   "Black",
   "Gray"
 ],
 "pricing": {
   "regular_price": 79.99,
   "sale_price": 64.99,
   "currency": "USD"
 }
}

Estos datos JSON formateados ahora pueden integrarse directamente con tu base de datos de productos, eliminando la necesidad de una lógica de análisis personalizada y reduciendo la posibilidad de errores.

Comprender la configuración de salida estructurada

La clave de unas salidas estructuradas eficaces y sin errores es definir correctamente tu esquema. Vamos a desglosar los elementos importantes de la configuración:

text={
   "format": {
       "type": "json_schema",        # Specifies we're using JSON Schema
       "name": "product_details",    # A descriptive name for this schema
       "schema": {
           # Your JSON Schema definition here
           "type": "object",
           "properties": {
               # Each property with type information, e.g.
               "product_name": {"type": "string"},
               # ... other properties
           },
           "required": ["product_name", ...], # All other properties
           "additionalProperties": False
       },
       "strict": True                # Enforce schema constraints strictly
   }
}

Los componentes más importantes son:

1. Definición del esquema: Describe la estructura, incluyendo todas las propiedades y sus tipos.
2. Campos obligatorios: Enumera las propiedades que deben incluirse en la respuesta.
3. Propiedades adicionales: Si se establece en False, se evitan los campos adicionales no definidos en el esquema.
4. Modo estricto: Cuando True, garantiza que el modelo sigue el esquema con precisión.

Consejos prácticos para utilizar salidas estructuradas

Para obtener los mejores resultados con salidas estructuradas, sigue estas directrices:

1. Diseña tu esquema cuidadosamente: Incluye todos los campos obligatorios, pero céntrate en la información esencial.
2. Utiliza tipos de datos adecuados: Haz coincidir los tipos de esquema con la forma en que utilizarás los datos (números para cálculos, cadenas para texto).
3. Establecer restricciones claras: Utiliza enum para campos con opciones limitadas y minimum /maximum para límites numéricos.
4. Prueba con entradas variadas: Asegúrate de que tu esquema maneja diferentes formatos de entrada y casos extremos.
5. Incluye descripciones claras: Añadir descripciones a los campos ayuda al modelo a interpretar qué información debe extraer.

Comparación con la API de finalización del chat

Mientras que la API de Respuestas proporciona salidas estructuradas a través de JSON Schema, la API de Finalizaciones de Chat ofrece un enfoque alternativo utilizando modelos Pydantic que es mucho más sencillo:

from pydantic import BaseModel, Field
from typing import List, Optional
from openai import OpenAI

client = OpenAI()

class ProductDetails(BaseModel):
   product_name: str
   category: str = Field(default=None)
   features: List[str]
   specifications: Optional[dict] = None
   colors: List[str]
   pricing: dict

# With Chat Completions API
completion = client.beta.chat.completions.parse(
   model="gpt-4o",
   messages=[
       {"role": "system", "content": "Extract structured product information."},
       {"role": "user", "content": product_description}
   ],
   response_format=ProductDetails
)

pydantic_product = completion.choices[0].message.parsed

Cada enfoque tiene sus ventajas:

• La API de respuestas utiliza el esquema JSON estándar directamente en la llamada a la API
• La API de finalización del chat se integra con el sistema de tipos de Python a través de Pydantic

En mi opinión, yo utilizaría la API de finalización de chat para evitar escribir esquemas JSON sin procesar. Eso hasta que, por supuesto, OpenAI añada soporte para modelos Pydantic a la API de Respuestas.

Para más información, consulta la Documentación de la API de Respuestas para Salidas Estructuradas.

Conclusión

La API de respuestas de OpenAI simplifica la forma en que los desarrolladores interactúan con los modelos lingüísticos, combinando los puntos fuertes de las API anteriores en una interfaz unificada que requiere menos código y complejidad. Es compatible con la generación de texto, el análisis de imágenes, la llamada a funciones y las salidas estructuradas, lo que hace que las capacidades de IA sean más accesibles y permite a los desarrolladores centrarse en resolver problemas empresariales en lugar de retos de integración.

A medida que continúes tu viaje con la API de respuestas, puede que estos recursos adicionales te resulten útiles para profundizar en tu comprensión y ampliar tus habilidades de implementación:

• Trabajar con la API de OpenAI
• Curso de Fundamentos de OpenAI
• GPT-4.5: Novedades del último modelo de OpenAI
• Investigación profunda con OpenAI
• GPT-4.5 Tutorial de llamada a funciones
• Tutorial de la API GPT-4.5
• OpenAI Agents SDK Tutorial