API Chat completions

Estructura de Chat Completions API y mensajes

La Chat Completions API de OpenAI funciona mediante un sistema de conversación estructurada donde cada interacción se organiza como una serie de mensajes con roles específicos. Aunque esta API sigue siendo funcional, es importante mencionar que desde comienzos de 2025 se recomienda utilizar la nueva API Responses para nuevos proyectos, ya que ofrece una interfaz más simplificada y moderna.

Anatomía de una llamada básica

Una llamada típica a la Chat Completions API requiere dos elementos fundamentales: el modelo que procesará la petición y una lista de mensajes que representan la conversación. 

La estructura básica sigue este patrón:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "user", "content": "Explica qué es la programación orientada a objetos"}
    ]
)

print(response.choices[0].message.content)

El objeto de respuesta contiene múltiples campos, pero el contenido generado se encuentra en response.choices[0].message.content. La estructura choices permite manejar múltiples respuestas cuando se solicitan, aunque por defecto se genera una sola.

Sistema de roles en los mensajes

Los mensajes en Chat Completions API utilizan tres roles principales que definen el contexto y propósito de cada intervención:

El rol **system** establece el comportamiento y personalidad del asistente. Este mensaje actúa como las instrucciones iniciales que guían cómo debe responder el modelo:

messages = [
    {
        "role": "system", 
        "content": "Eres un profesor de programación que explica conceptos de forma clara y con ejemplos prácticos."
    },
    {
        "role": "user", 
        "content": "¿Qué es una función en Python?"
    }
]

El rol **user** representa las intervenciones del usuario o las preguntas que se realizan al modelo. Estos mensajes contienen las consultas, instrucciones o información que el usuario proporciona:

{
    "role": "user",
    "content": "Necesito ayuda para crear una función que calcule el área de un círculo"
}

El rol **assistant** corresponde a las respuestas previas del modelo en la conversación. Incluir estos mensajes permite mantener el contexto conversacional y crear diálogos coherentes:

messages = [
    {"role": "user", "content": "¿Cómo se declara una variable en Python?"},
    {"role": "assistant", "content": "En Python se declara una variable simplemente asignándole un valor: nombre_variable = valor"},
    {"role": "user", "content": "¿Y cómo cambio su valor después?"}
]

Estructura del objeto mensaje

Cada mensaje en la lista debe seguir una estructura específica con campos obligatorios y opcionales:

mensaje = {
    "role": "user",           # Obligatorio: system, user, o assistant
    "content": "Tu pregunta"  # Obligatorio: el texto del mensaje
}

El campo content puede contener desde texto simple hasta instrucciones complejas. Es importante mantener la claridad y especificidad en el contenido para obtener respuestas más precisas:

# Mensaje simple
{"role": "user", "content": "Hola"}

# Mensaje con instrucciones específicas
{
    "role": "user", 
    "content": "Genera un ejemplo de código Python que lea un archivo CSV y muestre las primeras 5 filas"
}

Construcción de conversaciones

Para crear conversaciones coherentes, los mensajes se organizan cronológicamente en la lista. El modelo procesa toda la secuencia para generar respuestas contextualmente apropiadas:

conversacion = [
    {
        "role": "system",
        "content": "Eres un asistente especializado en debugging de código Python."
    },
    {
        "role": "user",
        "content": "Mi código da error: NameError: name 'x' is not defined"
    },
    {
        "role": "assistant",
        "content": "Este error indica que estás intentando usar una variable 'x' que no ha sido definida previamente. ¿Podrías mostrarme el código completo?"
    },
    {
        "role": "user",
        "content": "print(x + 5)"
    }
]

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=conversacion
)

Migración hacia API Responses

Aunque Chat Completions API sigue siendo completamente funcional, la nueva API Responses ofrece una interfaz más directa para casos de uso simples:

# Enfoque moderno con API Responses
response = client.responses.create(
    model="gpt-4.1",
    input="Explica el concepto de herencia en programación orientada a objetos"
)

print(response.output_text)

Esta nueva API simplifica significativamente el código para interacciones básicas, eliminando la necesidad de estructurar mensajes manualmente cuando no se requiere mantener contexto conversacional complejo.

La elección entre ambas APIs depende de las necesidades específicas: Chat Completions para conversaciones complejas con múltiples roles y contexto, y Responses para generación directa de texto sin complejidad conversacional.