Chat Completions vs Responses API en Python

Si trabajas con la librería de OpenAI, tarde o temprano te vas a topar con dos formas de pedirle algo al modelo: Chat Completions y Responses API. Aquí verás en qué se diferencian, cómo se ve cada una en código y por qué conviene construir proyectos nuevos con Responses API. Es contenido pensado para quien programa con Python y quiere entender qué está manteniendo o qué debería elegir.

Cuál es la diferencia entre Chat Completions y Responses API

Ambas nacen del mismo cliente de OpenAI, pero piensan la conversación de forma distinta. Chat Completions es el flujo clásico y Responses API es la forma más moderna de trabajar.

Con Chat Completions llamamos a client.chat.completions.create y todo gira alrededor de messages. Ahí armamos una conversación completa:

• Un mensaje de sistema para definir el comportamiento del modelo.
• Un mensaje de usuario con la pregunta.
• Mensajes anteriores del asistente si queremos mantener el contexto.

La parte clave está en quién guarda la memoria. Con Chat Completions el historial lo manejas tú: si quieres continuar la conversación, tienes que guardar los mensajes anteriores y volverlos a enviar en cada request.

¿Qué es Chat Completions en OpenAI? Es el flujo clásico que se llama con client.chat.completions.create y gira alrededor de una lista de messages. Tú manejas el historial manualmente enviándolo en cada llamada.

Con Responses API usamos client.responses.create y la estructura cambia. En vez de pensar solo en una lista de mensajes, piensas en instructions e input. Las instrucciones definen cómo debe comportarse el modelo y el input representa lo que el usuario pide en ese momento [00:58].

Por qué elegir Responses API para proyectos nuevos

Responses API está pensada para crecer mejor cuando necesitas herramientas, multimodalidad o continuidad conversacional. Y aquí viene lo interesante: la continuidad se maneja con algo como previous_response_id, en lugar de reenviar todo el historial a mano.

También es más directa al leer la respuesta, porque normalmente accedes al texto con response.output_text. El factor diferencial se resume así:

• Chat Completions gira alrededor de messages.
• Responses API gira alrededor de input, instructions, tools y continuidad conversacional.

Si mantienes un proyecto existente, Chat Completions todavía funciona bien. Pero si construyes algo nuevo, en especial una app con tools, agentes o flujos avanzados, Responses API es el camino más moderno [01:37].

¿Cuándo debo usar Chat Completions y cuándo Responses API? Usa Chat Completions para mantener código existente. Usa Responses API para proyectos nuevos, sobre todo si vas a integrar herramientas o agentes.

Cómo se ve cada API en el código

En el archivo main.py ya teníamos el cliente con client.responses.create. La comparación se hace agregando una segunda función que use Completions [02:31].

La función generate_text_with_chat_completions recibe el mismo parámetro prompt (un string) y devuelve un string. Adentro definimos una variable completion que llama a client.chat.completions.create, que es más corto y fácil de recordar que client.responses.create [03:22].

En lugar de instructions e input, aquí se define messages como un array donde cada objeto es un mensaje:

python completion = client.chat.completions.create( model=model, messages=[ {"role": "system", "content": "Eres un asistente experto en estrategias de contenido"}, {"role": "user", "content": prompt}, ], ) return completion.choices[0].message.content

El system prompt cumple el papel del instructions, y esa es la comparativa directa entre una función y otra [04:04]. Para leer la respuesta accedemos a completion.choices[0].message.content, porque la estructura que devuelve Completions es mucho más grande que la del Responses API [04:33].

Cómo reutilizar el prompt en ambos llamados

Como se usa el mismo prompt para las dos funciones, no hace falta duplicar el texto. Se guarda una vez en una variable prompt y se reutiliza en ambos llamados [05:34].

En main.py importamos las dos funciones: generate_text (la moderna) y generate_text_with_chat_completions (la legacy). Una llamamos modern y la otra legacy, e imprimimos cada resultado con su etiqueta. El usage, que muestra el consumo de tokens, solo está disponible en el Responses API, así que se deja arriba para medir cuántos tokens usamos y estimar el costo de cada llamada [06:45].

Qué diferencia de rendimiento se ve al ejecutar

Al correr main.py obtenemos las dos respuestas, cada una con su tag. La de Completions aparece marcada como Legacy API [07:23].

Lo primero que salta es el delay: hay una diferencia de tiempo notable entre la primera y la segunda respuesta. El Responses API suele ser mucho más rápido que Completions, aunque ambos entregan respuestas bastante completas [07:45].

En el ejemplo, el conteo de tokens del Responses API fue:

• Input tokens: 31.
• Output tokens: 1418.
• Total: 1449.

La estructura de respuesta del Legacy API es bastante parecida a la de Responses, solo que con un tiempo de espera mucho más amplio y lento [08:33].

Con la capacidad de reconocer y navegar entre ambos estilos de código, el siguiente paso es volver a Responses API y entrar a temas de producción: cómo funcionan los tokens, qué modelo elegir y cómo gestionar los costos de forma eficiente. ¿Ya te habías encontrado código con Chat Completions en algún proyecto? Cuéntanos en los comentarios.