API de Chat Completions de OpenAI: guía de funciones y uso

Crear una aplicación impulsada por IA no consiste solo en lograr que un modelo genere respuestas. También necesitas una forma confiable de gestionar conversaciones, orientar las respuestas y conectar todo con tu aplicación. La API de OpenAI Chat Completions lo hace posible al darles a los desarrolladores control sobre cómo la IA maneja los mensajes y genera respuestas. Si quieres entender cómo funciona y cómo usarla en tus propios proyectos, este artículo te explicará todo lo que necesitas saber.

La API de OpenAI Chat Completions permite a los desarrolladores integrar los modelos de lenguaje de OpenAI en aplicaciones y servicios. Genera respuestas a partir de una secuencia de mensajes y admite tareas como conversación, respuesta a preguntas, generación de contenido y análisis de texto.

Chat Completions sigue siendo compatible. Para proyectos nuevos, OpenAI recomienda la API de Responses. Esta guía se centra en Chat Completions para explicar su formato de mensajes, los parámetros de solicitud y su uso con SDK compatibles.

A diferencia del endpoint heredado de Completions (/v1/completions), que acepta un prompt de texto, Chat Completions acepta una lista estructurada de mensajes. Cada mensaje tiene un rol, como developer, user o assistant, que ayuda al modelo a interpretar las instrucciones y el contexto de la conversación. Los roles y tipos de contenido compatibles dependen del modelo seleccionado.

Los desarrolladores pueden usar la API para crear diversas funciones impulsadas por IA, entre ellas:

• Aplicaciones conversacionales: Crea chatbots de IA, asistentes virtuales y sistemas de atención al cliente que respondan a los mensajes de los usuarios.

• Generación de contenido: Genera artículos, descripciones de productos, correos electrónicos, resúmenes y otro contenido escrito.

• Análisis de texto: Clasifica texto, extrae información, analiza sentimientos e identifica puntos clave en documentos.

• Asistencia para programación: Genera fragmentos de código, explica conceptos de programación y ayuda a los desarrolladores a solucionar errores.

• Procesamiento de lenguaje: Traduce, reescribe, simplifica y corrige textos en distintos idiomas.

La API ofrece una forma flexible de conectar modelos de lenguaje con software existente, lo que permite a los desarrolladores incorporar respuestas generadas por IA en sus aplicaciones sin tener que crear ni alojar sus propios modelos de lenguaje.

La API de Chat Completions sigue un flujo de trabajo de solicitud y respuesta. Una aplicación envía una solicitud que contiene un identificador de modelo y una lista de mensajes al endpoint de la API. El modelo seleccionado procesa la entrada y devuelve una respuesta generada.

El flujo de trabajo básico incluye los siguientes pasos:

1. Preparar la conversación: La aplicación recopila la entrada del usuario y la organiza en una lista de mensajes. También se pueden incluir mensajes anteriores de la conversación para proporcionar contexto.

2. Enviar una solicitud a la API: La aplicación envía una solicitud POST a https://api.openai.com/v1/chat/completions con el modelo seleccionado y la lista de mensajes. Las solicitudes usan un encabezado Authorization: Bearer <API_KEY>. El método client.chat.completions.create() del SDK de Python se encarga de esta estructura de solicitud y de la autenticación.

3. Procesar la entrada: El modelo interpreta los mensajes, considera sus roles y contenido, y genera una respuesta según el contexto y los parámetros proporcionados.

4. Recibir la respuesta: Una solicitud sin transmisión devuelve una respuesta JSON que contiene la finalización generada y metadatos. Con la transmisión habilitada, la API envía una secuencia de eventos enviados por el servidor (SSE), que la aplicación procesa a medida que llegan.

5. Mostrar o procesar la salida: La aplicación extrae el mensaje generado y se lo muestra al usuario o lo pasa a otro componente de la aplicación.

El flujo de trabajo se basa en el modelo de solicitudes y respuestas de la API de OpenAI Chat Completions.

Para usar la API de Chat Completions de forma eficaz, los desarrolladores deben comprender sus principales parámetros de solicitud y cómo afectan el comportamiento del modelo.

El parámetro model especifica qué modelo de lenguaje procesa la solicitud. Los distintos modelos pueden ofrecer diferentes capacidades, velocidades de respuesta, rendimiento de razonamiento y precios.

Los desarrolladores deben seleccionar un modelo según la complejidad de la tarea, la calidad de respuesta esperada, los requisitos de latencia y el presupuesto.

El parámetro messages contiene un arreglo de mensajes de conversación. Por lo general, cada mensaje incluye un campo role y otro content.

Los roles comunes incluyen:

Elige el rol de instrucción compatible con tu modelo; no necesitas enviar mensajes system y developer para las mismas instrucciones. Para mantener el contexto entre turnos, incluye el historial de conversación relevante en cada solicitud. Los proveedores compatibles pueden admitir roles diferentes, así que sigue la documentación de sus propios modelos al adaptar una integración.

En los modelos y configuraciones que lo admiten, temperature controla la aleatoriedad del muestreo. La referencia de la API define un rango de 0 a 2, con un valor predeterminado de 1. Verifica la compatibilidad de parámetros del modelo seleccionado antes de establecer un valor personalizado.

• Temperatura más baja: Produce respuestas más enfocadas y predecibles, lo que la hace útil para clasificación, extracción de información y tareas estructuradas.

• Temperatura más alta: Permite mayor variación en el texto generado, lo que puede ser útil para la lluvia de ideas y la escritura creativa.

Algunas configuraciones de razonamiento no aceptan valores personalizados de temperature ni top_p. En esas configuraciones, omite estos parámetros de muestreo y usa en su lugar controles compatibles, como el esfuerzo de razonamiento y los límites de salida.

Cuando es compatible, top_p controla la selección de tokens mediante muestreo de núcleo. Establece el umbral de probabilidad acumulada que se usa para elegir los tokens candidatos.

Por ejemplo, un valor de 0.1 significa que el modelo considera tokens dentro del 10% más alto de la masa de probabilidad acumulada. Los valores más bajos suelen producir resultados más enfocados, mientras que los más altos permiten una mayor variación.

OpenAI recomienda ajustar temperature o top_p, en lugar de cambiar ambos al mismo tiempo.

El parámetro max_completion_tokens establece la cantidad máxima de tokens que el modelo puede generar en una respuesta, incluidos los tokens de razonamiento cuando corresponda.

Establecer un límite adecuado ayuda a los desarrolladores a controlar la longitud de la salida y administrar el consumo de tokens. Si el modelo alcanza este límite antes de completar su respuesta, el completado puede terminar con un motivo de finalización length.

El parámetro stream determina si la API devuelve la respuesta generada de una sola vez o progresivamente a medida que se produce.

• false: Devuelve la respuesta completa cuando finaliza la generación.

• true: Transmite los datos de la respuesta a la aplicación mediante eventos enviados por el servidor (SSE).

La transmisión es útil para interfaces de chat y aplicaciones en las que los usuarios se benefician de ver las respuestas aparecer progresivamente, en lugar de esperar toda la salida.

El parámetro response_format selecciona el formato de salida en los modelos compatibles. El texto es el valor predeterminado. Establecer type en json_object activa el modo JSON, que produce JSON válido, pero no impone un esquema específico. Incluye en los mensajes una instrucción para devolver JSON.

Para campos y tipos de datos predecibles, usa Salidas estructuradas basadas en JSON Schema con type: "json_schema" y strict: true en un modelo compatible. En modo estricto, solo puede usarse el subconjunto compatible de JSON Schema. Antes de procesar el resultado, verifica si hubo un rechazo o si la respuesta se truncó. Consulta la guía de Salidas estructuradas para conocer los detalles de configuración.

El parámetro tool_choice controla la selección de herramientas cuando el modelo admite llamadas a herramientas mediante Chat Completions. La compatibilidad depende tanto del modelo como de su configuración de razonamiento; algunos modelos más recientes requieren la Responses API para usar herramientas. Verifica estos requisitos antes de agregar herramientas a una solicitud.

Las configuraciones comunes incluyen:

• none: Impide que el modelo llame herramientas.

• auto: Permite que el modelo decida si llama una herramienta disponible.

• required: Exige que el modelo llame una o más herramientas.

Esta capacidad admite llamadas a funciones, lo que permite que una aplicación conecte las decisiones generadas por el modelo con funciones, bases de datos y servicios externos. La aplicación es responsable de ejecutar la función solicitada y devolver su resultado al modelo.

Usa la referencia de la API de Chat Completions para consultar las definiciones de parámetros y los requisitos de compatibilidad de los modelos. El siguiente ejemplo en Python usa una solicitud básica de texto sin herramientas.

Los desarrolladores pueden acceder a la API de Chat Completions mediante solicitudes HTTP o un SDK oficial. El siguiente ejemplo usa Python para enviar una solicitud conversacional y obtener la respuesta generada.

Paso 1. Obtén una clave de API

Crea una clave de API en la plataforma de API de OpenAI y asegúrate de que tu cuenta tenga acceso al modelo seleccionado y suficientes créditos de API o capacidad de facturación. Guarda la clave en una variable de entorno en lugar de hacerlo en el código fuente de la aplicación. En macOS o Linux, ejecuta:

Reemplaza YOUR_API_KEY por tu propia clave. En Windows, establece la misma variable OPENAI_API_KEY en tu shell o entorno del sistema.

Paso 2. Instala el SDK de Python de OpenAI

Instala la biblioteca oficial de Python con pip:

Paso 3. Inicializa el cliente de API

Importa el SDK e inicializa el cliente. OpenAI() lee automáticamente la variable de entorno OPENAI_API_KEY establecida en el paso 1.

Paso 4. Envía una solicitud de completado de chat

Llama a client.chat.completions.create() con un modelo y una lista de mensajes. Este ejemplo usa gpt-6-astra con un esfuerzo de razonamiento bajo y un límite total de generación de 4,096 tokens. Si este modelo no está disponible para tu cuenta, elige un modelo compatible con Chat Completions y ajusta los parámetros según su documentación.

En este ejemplo:

• model identifica el modelo de lenguaje usado para generar la respuesta.

• messages proporciona instrucciones y entrada del usuario.

• reasoning_effort establece el esfuerzo de razonamiento para los modelos compatibles con este parámetro.

• max_completion_tokens limita los tokens generados, incluidos los tokens de razonamiento. No garantiza una cantidad específica de texto visible.

• response.choices[0].message.content extrae la respuesta del asistente.

Procesa la respuesta de la API

Para esta solicitud sin transmisión, la API devuelve JSON que contiene la finalización y los metadatos de la solicitud. El SDK de Python lo analiza en un objeto ChatCompletion, por lo que el ejemplo accede a los campos mediante atributos como response.choices[0].message.content.

Los campos importantes de la respuesta incluyen:

El campo finish_reason puede ayudar a los desarrolladores a entender cómo terminó una generación. Los valores comunes incluyen stop, length y tool_calls.

Los desarrolladores también pueden inspeccionar el campo usage para monitorear el consumo de tokens de entrada y salida, lo cual resulta útil para estimar los costos de la API y optimizar el uso de la aplicación.

Este ejemplo muestra una respuesta de texto básica. Al agregar transmisión, salida estructurada o herramientas, actualiza tanto la solicitud como la lógica de manejo de respuestas para que coincidan con el modelo y el endpoint seleccionados.

Para los desarrolladores que exploran alternativas a la API de Chat Completions de OpenAI, Kimi API brinda acceso a los modelos de lenguaje grandes de Moonshot AI mediante un formato de API compatible con OpenAI.

Kimi ofrece interfaces de Chat Completions, Responses y Messages. El siguiente ejemplo usa su endpoint de Chat Completions compatible con OpenAI para que puedas reutilizar el flujo de trabajo del SDK presentado anteriormente. Configura una clave de Kimi API, establece la URL base de Kimi y selecciona un modelo compatible. Consulta la documentación de Kimi para conocer los parámetros de los modelos, los roles de los mensajes y la compatibilidad con herramientas.

Paso 1. Obtén una clave de Kimi API

Regístrate en la plataforma de Kimi API y crea una clave de API en la consola para desarrolladores. Revisa tu saldo, acceso a modelos y límites de tasa de la cuenta antes de realizar tu primera solicitud.

Guarda la clave de Kimi en una variable de entorno independiente. En macOS o Linux, ejecuta:

Reemplaza YOUR_KIMI_API_KEY por tu propia clave de Kimi. En Windows, configura la misma variable KIMI_API_KEY en tu entorno.

Paso 2. Instala el SDK de Python de OpenAI

Si el SDK aún no está instalado, ejecuta:

Paso 3. Configura el cliente de Kimi API

Crea un kimi_client independiente con la URL base de Kimi y la variable KIMI_API_KEY configurada en el paso 1. Leer la clave con os.environ hace que la ausencia de una variable de entorno sea inmediatamente visible como un error.

Paso 4. Envía una solicitud de Chat Completions

Usa el mismo método del SDK con el cliente de Kimi. Esta solicitud selecciona kimi-k3, usa el rol system compatible con Kimi para las instrucciones y devuelve una respuesta de texto sin transmisión.

• Opciones de modelos para distintas cargas de trabajo: Kimi K3.1 Pro admite razonamiento complejo, programación de largo alcance y trabajo basado en conocimiento. Su variante Highspeed ofrece resultados más rápidos con las mismas capacidades del modelo. El ejemplo anterior usa Kimi K3; consulta la lista actual de modelos para conocer la disponibilidad y las pautas de migración.

• Compatibilidad con la API de OpenAI: Los desarrolladores familiarizados con el formato de Chat Completions de OpenAI pueden reutilizar una estructura de solicitud similar y flujos de trabajo del SDK compatibles al integrar modelos de Kimi.

• Conversaciones de varios turnos: Los desarrolladores pueden proporcionar historiales de mensajes para admitir conversaciones conscientes del contexto, asistentes virtuales y aplicaciones interactivas.

• Transmisión y llamada a funciones: La API admite respuestas en transmisión y flujos de trabajo de llamada a herramientas, lo que permite a los desarrolladores crear aplicaciones más interactivas y conectar modelos con funciones externas.

• Entrada multimodal: Los modelos de Kimi compatibles pueden procesar distintos tipos de entrada, incluidos texto, imágenes y video, según las capacidades del modelo.

Al trabajar con la API de Chat Completions, los desarrolladores pueden encontrar errores relacionados con la autenticación, la configuración de la API, la disponibilidad de modelos o los límites de solicitudes. Comprender estos problemas comunes puede ayudarte a identificar errores y lograr que tu integración funcione correctamente:

• Clave de API no válida o ausente: Pueden producirse errores de autenticación, como HTTP 401, cuando la clave de API es incorrecta, está vencida, fue revocada o no está configurada correctamente. Verifica que la clave sea válida, que la variable de entorno se cargue correctamente y que la solicitud incluya las credenciales de autenticación adecuadas.

• URL base de la API incorrecta: Las solicitudes enviadas a un endpoint incorrecto pueden devolver errores como 404 o fallas de conexión. Verifica que la URL base coincida con la documentación del proveedor de la API y que la solicitud use la ruta de endpoint correcta. Al cambiar entre OpenAI y proveedores compatibles, recuerda actualizar la URL base según corresponda.

• ID de modelo no válido o no disponible: Una solicitud puede fallar si el nombre del modelo especificado es incorrecto, no está disponible para tu cuenta o no es compatible con el endpoint seleccionado. Consulta la documentación de modelos del proveedor y confirma que el ID del modelo coincida con el disponible para tu cuenta de API.

• Se excedió la longitud de contexto: Si los mensajes de entrada combinados y la salida generada superan la ventana de contexto del modelo, la API puede rechazar la solicitud. Reduce la longitud de la entrada, elimina el historial de conversación innecesario o resume los mensajes anteriores antes de enviar la solicitud de nuevo.

• Salida truncada: Una respuesta puede detenerse antes de completar el contenido solicitado si alcanza el límite de max_completion_tokens. Aumenta el límite de tokens cuando sea compatible o divide una tarea de generación extensa en solicitudes más pequeñas. También puedes inspeccionar choices[].finish_reason para comprobar si la respuesta terminó debido al límite de length.

• Se excedió el límite de tasa o la cuota: En OpenAI, HTTP 429 puede indicar un límite de tasa de solicitudes o tokens, un límite de gasto u otra restricción de uso. Inspecciona el tipo y el código de error antes de volver a intentarlo. Ante un límite de tasa temporal, reduce la frecuencia de las solicitudes y respeta Retry-After cuando se proporcione, o usa una espera exponencial.

Si el error indica créditos agotados o un límite de facturación o gasto, revisa el saldo y la configuración de facturación de la cuenta; los reintentos repetidos no restaurarán el acceso. Al usar Kimi u otro proveedor compatible, consulta la documentación de códigos de error de ese proveedor, ya que los códigos de estado y las reglas de cuota pueden variar.

Para una depuración más eficiente, revisa el código de estado HTTP y el mensaje de error devueltos por la API antes de cambiar los parámetros de tu solicitud. Estos detalles pueden ayudar a distinguir problemas de autenticación, errores de configuración y límites de uso.

La API de Chat Completions puede admitir una amplia variedad de escenarios de aplicación. Su formato estructurado de mensajes y sus parámetros de generación personalizables la hacen adecuada tanto para funciones sencillas basadas en texto como para flujos de trabajo de IA más complejos.

• Chatbots de IA y asistentes virtuales: Los desarrolladores pueden usar la API para crear asistentes conversacionales para sitios web, aplicaciones móviles y plataformas de servicio al cliente. Al incluir mensajes anteriores en solicitudes posteriores, las aplicaciones pueden mantener el contexto de la conversación y ofrecer respuestas más relevantes.

• Creación de contenido y edición de texto: La API puede generar y transformar texto según las instrucciones del usuario. Las aplicaciones pueden usarla para redactar publicaciones de blog, escribir textos de marketing, resumir contenido extenso, reescribir párrafos y ajustar estilos de redacción para diferentes públicos y propósitos.

• Clasificación de texto y extracción de información: Las empresas pueden integrar la API en flujos de trabajo que procesan grandes volúmenes de texto. Por ejemplo, puede clasificar comentarios de clientes, identificar sentimientos, extraer información importante de mensajes y organizar contenido no estructurado en categorías predefinidas.

• Asistentes de programación: La API puede respaldar herramientas de desarrollo de software al generar código, explicar conceptos de programación, sugerir soluciones y ayudar a los desarrolladores a identificar errores. Las aplicaciones también pueden conectar el modelo con herramientas de desarrollo externas mediante llamadas a funciones.

• Flujos de trabajo empresariales con IA: Los desarrolladores pueden incorporar la API en aplicaciones empresariales para automatizar tareas repetitivas relacionadas con el lenguaje. Algunos ejemplos son procesar consultas de clientes, generar informes, extraer información de documentos y preparar respuestas según instrucciones predefinidas.

La API Chat Completions de OpenAI ofrece a los desarrolladores una forma práctica de incorporar IA conversacional en sus aplicaciones y crear experiencias de usuario más útiles. Elegir el modelo adecuado, comprender sus parámetros y gestionar cuidadosamente las respuestas de la API puede marcar una diferencia real en el rendimiento de una aplicación. Sin embargo, los desarrolladores no tienen que depender de un solo proveedor al crear soluciones con IA. Si desea explorar otra opción, pruebe Kimi API y vea cómo su configuración compatible con OpenAI se adapta a sus necesidades de desarrollo.