API de Chat Completions: cómo funciona y cómo usarla

Ya sea que estés creando un chatbot de IA o agregando funciones conversacionales a una aplicación, es importante entender cómo la IA maneja las conversaciones. La API de Chat Completions lo hace posible al conectar aplicaciones con modelos de IA para generar respuestas pertinentes y similares a las humanas. Con funciones como la integración con Python, la transmisión en streaming y las llamadas a herramientas, los desarrolladores pueden crear aplicaciones más interactivas. Exploremos cómo funciona, cómo usarla y cómo proveedores como Kimi API respaldan el desarrollo flexible de IA.

La API de Chat Completions es una interfaz que permite a las aplicaciones enviar una secuencia de mensajes a un modelo de IA y recibir una respuesta del asistente, y admite conversaciones de un solo turno y de varios turnos. Por ejemplo, puedes usar Kimi K3.1 Pro para responder una pregunta sobre decoradores de Python y luego hacer una pregunta de seguimiento:

• Primera solicitud: Envía el mensaje del usuario: "¿Qué es un decorador de Python?" Kimi devuelve un mensaje del asistente que explica el concepto.

• Segunda solicitud: Para continuar la conversación, envía el mensaje anterior del usuario, el mensaje completo del asistente de Kimi y un nuevo mensaje del usuario: "¿Puedes darme un ejemplo?"

El arreglo messages contiene el contexto necesario para cada solicitud. Tres decisiones de diseño clave hacen que esta interfaz tenga una adopción generalizada:

• Historial administrado por la aplicación: Las aplicaciones administran el historial de conversación e incluyen el contexto pertinente en cada solicitud, lo que da a los desarrolladores control sobre lo que ve el modelo.

• Roles comunes de los mensajes: Los roles comunes incluyen system (instrucciones), user (entrada), assistant (salida del modelo, que se devuelve para el contexto de varios turnos) y tool (resultados de llamadas a funciones). En conjunto, permiten expresar instrucciones, diálogo e interacciones con herramientas.

• Capacidades flexibles: Según la compatibilidad del modelo, la interfaz puede manejar transmisión en tiempo real, llamadas a herramientas, entradas visuales y salidas estructuradas. Kimi K3.1 Pro admite estas capacidades.

Los siguientes ejemplos usan Kimi K3.1 Pro y el SDK de OpenAI para Python para mostrar cómo configurar el cliente, enviar solicitudes, manejar respuestas e implementar llamadas a herramientas:

Instala el SDK de OpenAI para Python:

Configura tu clave de Kimi API como una variable de entorno:

No necesitas una clave de OpenAI API. El SDK de OpenAI para Python funciona como biblioteca cliente, mientras que tu clave de Kimi API y la URL base autentican y enrutan las solicitudes a Kimi.

Inicializa el cliente y envía tu primera solicitud:

Este ejemplo usa el endpoint internacional de Kimi API. Para conocer la configuración oficial y los detalles del modelo, consulta la guía de inicio rápido de Kimi K3.1 Pro.

Estos parámetros cubren las principales opciones disponibles al llamar a Kimi K3.1 Pro mediante la API de Chat Completions:

Nota: Kimi K3.1 Pro usa configuraciones de muestreo fijas. No agregues temperature ni top_p a las solicitudes. Consulta la referencia de la API de Chat Completions para ver los detalles de los parámetros y los valores admitidos.

Después de una solicitud exitosa, puedes acceder a los principales campos de respuesta mediante el objeto de completado devuelto:

• choices[0].message – Contiene la respuesta del asistente, incluidos content o tool_calls cuando el modelo solicita una función.

• choices[0].finish_reason – Indica por qué se detuvo la generación, por ejemplo, stop, length o tool_calls.

• usage – Proporciona información sobre el uso de token, incluidos los recuentos de token de entrada, salida y caché cuando están disponibles.

Para una respuesta de texto básica, lee choices[0].message.content. Si el modelo devuelve tool_calls, tu aplicación debe ejecutar las funciones solicitadas y enviar sus resultados en una solicitud posterior.

Configura stream=True para recibir la respuesta de Kimi en fragmentos incrementales. El siguiente ejemplo reutiliza el client configurado anteriormente e imprime la respuesta final a medida que llega:

Kimi K3.1 Pro devuelve el contenido de razonamiento por separado de la respuesta final. Este ejemplo solo imprime delta.content, por lo que muestra la respuesta final sin procesar el campo reasoning_content independiente.

Las llamadas a herramientas permiten que Kimi solicite funciones externas cuando una tarea requiere información o acciones que van más allá de la propia respuesta del modelo. Por ejemplo, si un usuario pregunta: "¿Debo llevar un paraguas hoy en Tokio?", Kimi puede solicitar una función get_weather para obtener el pronóstico.

El flujo de trabajo tiene tres pasos:

1. Declara la función: Define get_weather y los argumentos que espera en el parámetro tools.

2. Ejecuta la herramienta: Kimi devuelve una entrada tool_calls con el nombre y los argumentos de la función. Tu aplicación ejecuta la función correspondiente y obtiene los datos meteorológicos.

3. Envía el resultado de vuelta: Agrega a la conversación el mensaje completo del asistente de Kimi y el resultado de la herramienta (usando el tool_call_id correspondiente); luego, vuelve a llamar a Kimi para generar una respuesta dirigida al usuario.

El siguiente ejemplo reutiliza el client configurado anteriormente. Antes de ejecutarlo, asegúrate de haber implementado una función get_weather(city) que devuelva datos meteorológicos serializables en JSON. La función la ejecuta tu aplicación, no Kimi.

Aquí, get_weather() representa una función implementada por tu aplicación, no una función que Kimi ejecute directamente. Kimi decide cuándo solicitarla y proporciona los argumentos; tu aplicación realiza la operación y devuelve el resultado.

En producción, implementa un bucle que procese cada llamada a herramienta, agregue los resultados correspondientes a la conversación y envíe los mensajes actualizados a Kimi. Repite este ciclo hasta que el modelo devuelva una respuesta final sin solicitar herramientas adicionales.

Muchos proveedores admiten el formato OpenAI Chat Completions, lo que permite a los desarrolladores reutilizar SDK y estructuras de solicitudes conocidos. Por lo general, el cambio implica actualizar la URL base, la clave de API y el ID del modelo, y luego comprobar los parámetros admitidos y el manejo de respuestas. Al comparar proveedores, considera los siguientes factores:

1. Fidelidad de compatibilidad: Verifica que la transmisión en tiempo real, las llamadas a herramientas, las salidas estructuradas y los informes de usage funcionen como espera tu aplicación. La compatibilidad con el mismo formato de API no garantiza que todos los proveedores ofrezcan funciones idénticas ni el mismo comportamiento de respuesta.

2. Calidad del modelo para tu carga de trabajo: La combinación de idiomas y los tipos de tareas son más importantes que las pruebas comparativas genéricas.

3. Ventana de contexto: Los modelos de contexto largo pueden simplificar algunos flujos de trabajo con documentos al procesar más material de origen en una sola solicitud.

4. Estructura de costos: El almacenamiento en caché y los descuentos por lotes suelen tener más peso que los precios por token anunciados.

5. Amplitud del ecosistema: Endpoints compatibles adicionales, como Responses y Anthropic Messages, pueden ofrecer más opciones de integración y flexibilidad a medida que evoluciona tu aplicación.

Vale la pena considerar Kimi API, desarrollada por Moonshot AI, si buscas un proveedor compatible con OpenAI, en especial para aplicaciones en chino, procesamiento de documentos extensos y agentes de programación. Combina patrones conocidos de integración de API con las capacidades de contexto largo y razonamiento de Kimi.

Si tu aplicación ya usa el SDK de Python de OpenAI, puedes integrar Kimi sin tener que reescribir todo el flujo de solicitudes. Solo actualiza la configuración de la API, incluidos base_url, api_key y el ID del modelo, y conserva la conocida interfaz de Chat Completions.

Por ejemplo, el siguiente código lee un informe local de report.txt, envía su contenido a Kimi K3.1 Pro para resumirlo y transmite la respuesta generada:

Aquí, client reutiliza el cliente de Kimi inicializado previamente con tu clave de API, leída desde una variable de entorno. Elige la URL base según tu región: https://api.moonshot.ai/v1 para la plataforma internacional o https://api.moonshot.cn/v1 para usuarios que acceden a la API desde China continental.

Este enfoque te permite conservar tu flujo de trabajo actual con el SDK de OpenAI mientras usas modelos Kimi para tareas como el resumen de documentos y otras aplicaciones basadas en API.

• Un modelo insignia con una ventana de contexto de 1M tokens: Kimi K3.1 Pro admite una ventana de contexto de hasta 1M tokens y comprensión visual nativa. Los desarrolladores pueden trabajar con bases de código extensas, documentos de la extensión de un libro e imágenes en un solo flujo de trabajo, por lo que resulta adecuado para razonamiento complejo, programación y aplicaciones multimodales.

• Optimización flexible de costos: Kimi API admite el almacenamiento en caché automático del contexto para prefijos de solicitudes repetidos y la inferencia mediante Batch API para tareas a gran escala que no requieren respuestas en tiempo real. La facturación de caché y los precios de Batch dependen del modelo y de las reglas de precios aplicables. Consulta los precios oficiales de Kimi API para conocer las tarifas actuales y los detalles de facturación.

• Compatibilidad entre ecosistemas de API: Kimi ofrece endpoints de Chat Completions y Responses API compatibles con OpenAI, además de un endpoint compatible con Anthropic Messages. Los desarrolladores pueden integrar Kimi K3.1 Pro en flujos de trabajo existentes mediante SDK y formatos de API conocidos, con ajustes según el endpoint y las funciones admitidas.

Comenzar con Chat Completions API es sencillo: configura tus credenciales de API, envía una solicitud y lee la respuesta generada desde choices[0].message.content. Cuando tu primera llamada a la API funcione, podrás ampliar la integración según las necesidades de tu aplicación agregando conversaciones de varios turnos, respuestas transmitidas o llamadas a herramientas. ¿Listo para desarrollar con Kimi? Obtén tu clave de Kimi API y comienza a realizar solicitudes a la API.