Guía de integración API y uso de agentes de Kimi K3.1 Pro
Kimi K3.1 Pro pertenece a la serie K3.1 de Moonshot AI y está orientado a programación, creación 3D, investigación financiera y tareas prolongadas con agentes. Su ID oficial para API es kimi-k3.1-pro y la URL base del OpenAI SDK es https://api.moonshot.cn/v1. El modo de pensamiento está siempre activado; la intensidad de razonamiento puede fijarse en low, high o max, con max como valor predeterminado. Inicio rápido oficial
Esta guía explica la integración, el razonamiento, la visión y los ciclos de herramientas según la documentación oficial. Los resultados de referencia publicados por el proveedor son evaluaciones del propio proveedor, no pruebas de Guishu Intelligence.
Información clave
| Elemento | Información verificada |
|---|---|
| ID oficial del modelo | kimi-k3.1-pro |
| URL base oficial de API | https://api.moonshot.cn/v1 |
| Intensidad de razonamiento | low, high, max; max por defecto |
| Modo de pensamiento | Siempre activado |
| Contexto | La documentación oficial indica compatibilidad con 1 millón de tokens |
| Variante de alta velocidad | kimi-k3.1-pro-highspeed; modelo independiente; compruebe disponibilidad y precio en el catálogo de cada plataforma |
| Fecha de verificación de la documentación | 2026-10-24 |
Las capacidades y variantes se basan en la documentación oficial de Kimi K3.1 Pro. Las versiones, el acceso y los precios pueden cambiar; consulte los precios de modelos para ver la disponibilidad en nuestra plataforma.
¿Para qué sirve esta actualización?
El punto fuerte de K3.1 Pro son los trabajos de varios pasos: entender requisitos, generar un artefacto, comprobar el resultado y modificarlo a partir de comentarios. Un contexto de un millón de tokens permite incluir más material, pero el éxito de una tarea larga también depende de las herramientas, el entorno y los criterios de aceptación. Los siguientes ejemplos cubren programación, creación 3D e investigación financiera; proceden de experiencias de terceros y demostraciones del proveedor, no de ejecuciones nuestras.
Cámara 3D: comprobar si la estructura cambia con los parámetros
En su artículo «Los modelos chinos han dado otro gran paso: prueba de Kimi K3.1 Pro», Liu Xiaopai pidió a varios modelos crear una cámara interactiva. Según su informe, K3.1 Pro generó 34 piezas seleccionables y 9 láminas de diafragma, y 35 lecturas ópticas cumplieron sus criterios. En una segunda ronda, al cambiar el objetivo de 50 mm a 85 mm, el modelo también modificó la geometría en lugar de limitarse a cambiar la etiqueta.
El mismo caso mostró defectos: las unidades de exportación no se trataron como se había solicitado y había un problema de separación entre el chasis y el diafragma. En tareas de diseño conviene comprobar conjuntamente dimensiones, interacción, archivos exportados y modificaciones posteriores, en vez de valorar una sola imagen renderizada. El autor utilizó distintos entornos de herramientas de programación, por lo que sus impresiones no son una comparación con variables controladas.
Mapa de juego: crear una herramienta y dejar que el agente la use
El mismo autor creó también un editor de mapas de Terraria para el navegador. Los bloques debían respetar las reglas del juego y el mapa exportado debía poder volver a utilizarse en el juego. Después pidió a K3.1 Pro construir un escenario con el editor generado. Esta tarea combina comprensión de formatos de archivo, desarrollo de interfaz y operación de herramientas, y se acerca más a un flujo de trabajo real que generar un fragmento de código de demostración. El autor observó fortalezas visuales distintas en Kimi y los modelos comparados; es una observación personal, no una conclusión estética universal.
Investigación financiera: revisar fórmulas y referencias, no solo conclusiones
Los materiales de Zenan, Zhang Qian y Panda, del equipo editorial de jiqizhixin.com, reúnen ejemplos de modelización financiera, informes de investigación e ingeniería 3D. La documentación oficial también muestra un modelo financiero con supuestos operativos ajustables y un informe de investigación con fuentes. Lo útil de estos ejemplos es el criterio de revisión: ¿las fórmulas se actualizan al cambiar los supuestos?, ¿se pueden rastrear las cifras clave hasta los archivos originales?, ¿se puede abrir cada referencia del informe? Una demostración del proveedor no garantiza la exactitud para cualquier tarea financiera. Descripción oficial de capacidades y ejemplos
En la fecha de verificación de este artículo, el proveedor indicó que esperaba abrir los pesos completos antes del 4 de noviembre. Es un plan, no una publicación ya realizada; las funciones 3D de la aplicación oficial tampoco implican que la API incluya una herramienta de modelado.
Llamada API básica
El ejemplo oficial utiliza Python 3.9+ y OpenAI SDK. Guarde la clave API en una variable de entorno; no la escriba en el código fuente ni la envíe al repositorio.
python3 -m pip install --upgrade 'openai>=1.0'
export MOONSHOT_API_KEY="your-api-key"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.cn/v1",
)
result = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explica en tres puntos cómo diseñar un proceso fiable de revisión de código."}],
reasoning_effort="high",
)
print(result.choices[0].message.content)
Para llamar directamente a Moonshot, utilice una clave emitida por Moonshot y la URL base oficial anterior. Si usa un servicio compatible de terceros, sustituya la URL base, la clave y el ID del modelo por los que proporcione ese servicio; no entregue credenciales oficiales a terceros. Los modelos disponibles y la facturación de Guishu Intelligence se indican en la página de precios.
Cómo elegir la intensidad de razonamiento
K3.1 Pro siempre permanece en modo de pensamiento. reasoning_effort controla la intensidad del razonamiento, no activa ni desactiva ese modo. La documentación oficial ofrece low, high y max, con max como valor predeterminado. Explicación oficial de la intensidad de razonamiento
- Para respuestas breves o transformaciones con requisitos claros, puede empezar por
low. - Para cambios de código en varios pasos, análisis y planificación, pruebe primero
high. - En tareas complejas que requieren razonamiento más profundo, compare la calidad, latencia y coste real de
max.
Son recomendaciones de flujo de trabajo, no garantías de rendimiento. En producción, evalúe la precisión, latencia y coste con sus propias tareas.
Conversaciones de varios turnos: conservar el mensaje assistant completo
Para conversaciones de varios turnos y respuestas de herramientas, la documentación oficial indica que se debe añadir a la siguiente solicitud el mensaje assistant completo devuelto por la API, no solo el texto content. Los campos estructurados, como las llamadas a herramientas, pueden ser necesarios en los pasos siguientes. Documentación oficial sobre conversaciones de varios turnos
messages = [{"role": "user", "content": "Enumera primero el plan de migración y luego explica los riesgos."}]
first = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=messages,
reasoning_effort="high",
)
messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "Convierte la sección de riesgos en una lista de comprobación."})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)
Si la aplicación debe conservar sesiones entre solicitudes, guarde los campos de mensaje requeridos por el protocolo y compruebe en la documentación oficial cómo serializa el SDK los objetos de mensaje.
Llamadas a herramientas y ciclo de agente
La aplicación define y ejecuta las herramientas: el modelo genera una llamada, la aplicación valida sus parámetros, ejecuta la función real y devuelve el resultado al modelo. No ejecute directamente la salida del modelo como si fuera un comando fiable.
import json
tools = [{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Consultar el estado de un pedido",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Consulta el estado del pedido A-104"}]
response = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
assistant = response.choices[0].message
messages.append(assistant) # Conservar el mensaje assistant completo
for call in assistant.tool_calls or []:
args = json.loads(call.function.arguments)
# En una aplicación real, valide primero los parámetros y permisos del usuario; luego llame a la función empresarial controlada.
tool_result = {"order_id": args["order_id"], "status": "processing"}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(tool_result),
})
final = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)
La guía oficial de llamadas a herramientas también exige devolver cada resultado con su tool_call_id correspondiente y conservar el mensaje assistant completo en el turno siguiente. La aplicación debe implementar autenticación, validación de parámetros, límites de tiempo, idempotencia y auditoría.
Entrada visual: utilizar una matriz de objetos
La documentación oficial especifica que content en los mensajes visuales es una matriz de objetos, no una cadena serializada. El ejemplo transmite la imagen mediante una Data URL Base64; el flujo de archivos compatible también permite referencias ms://. No suponga que se puede leer directamente cualquier URL pública de imagen. Instrucciones oficiales de entrada visual
import base64
from pathlib import Path
image_data = base64.b64encode(Path("diagram.png").read_bytes()).decode()
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {
"url": f"data:image/png;base64,{image_data}"
}},
{"type": "text", "text": "Describe los componentes del sistema y sus conexiones en el diagrama."},
],
}],
)
print(response.choices[0].message.content)
Antes de integrar, compruebe los límites de formato y tamaño de imagen y de la interfaz de archivos. Antes de enviar imágenes sensibles a un modelo externo, revise también las normas de tratamiento de datos de su organización.
Cómo interpretar los benchmarks oficiales y las experiencias de terceros
Moonshot publica una puntuación de 65,7 % de K3.1 Pro en Terminal-Bench 4.0 y una comparación con GPT-6 Astra y Claude Opus 5.5. Son resultados del proveedor: deben interpretarse según el conjunto de tareas, la configuración de prueba y la fecha de publicación, y no permiten extrapolar la tasa de éxito a todas las tareas de programación. Presentación oficial del modelo y benchmarks
El autor externo Liu Xiaopai compartió experiencias, incluida una cámara 3D interactiva, y su valoración personal de los modelos comparados. No es una prueba de Guishu Intelligence ni una comparación uniforme y reproducible. Para evaluar un modelo, utilice sus propios repositorios, restricciones de diseño y casos fallidos; registre prompts, herramientas, reintentos, latencia y costes.
Lista de comprobación de integración
- Confirme si llama directamente al proveedor oficial o a un servicio compatible, y utilice el ID de modelo, URL base y clave correspondientes.
- Empiece con una intensidad de razonamiento menor y compare gradualmente calidad, latencia y factura en tareas representativas.
- En escenarios multi-turno y de agente, conserve el mensaje assistant completo y asocie correctamente los resultados de herramientas.
- Construya los mensajes visuales como matrices de objetos; para imágenes locales, utilice la codificación o el flujo de archivos admitido oficialmente.
- Defina límites de permisos, validación de parámetros, tiempos de espera y gestión de errores para la ejecución de herramientas.
- Antes del despliegue, confirme el catálogo actual, las regiones disponibles y los precios; no reutilice una configuración antigua sin verificarla.
Preguntas frecuentes
¿Cuál es el ID del modelo API de Kimi K3.1 Pro?
La documentación oficial indica kimi-k3.1-pro. La variante de alta velocidad se denomina kimi-k3.1-pro-highspeed; no deben confundirse en la configuración.
¿Cuál es la intensidad de razonamiento predeterminada?
La documentación oficial enumera low, high y max, con max por defecto. El modo de pensamiento del modelo siempre está activo.
¿Puedo enviar directamente una URL de imagen?
La documentación oficial no admite URL públicas de imágenes. Use una matriz de objetos visuales con una Data URL Base64 o, mediante el flujo de archivos, una referencia ms://.
¿Por qué un agente debe devolver el mensaje assistant completo?
Puede incluir campos estructurados como llamadas a herramientas. Si solo se conserva el texto, se pierde información necesaria para la interacción posterior; el resultado de la herramienta también debe llevar el tool_call_id correspondiente.
¿Guishu Intelligence ofrece Kimi K3.1 Pro?
Consulte la página de precios para conocer los modelos, rutas y precios disponibles actualmente. Que el proveedor ofrezca acceso API directo no significa que este modelo o su variante de alta velocidad esté disponible aquí.
Lecturas relacionadas
Fecha de verificación de la información oficial: 2026-10-24. Las capacidades, parámetros API y condiciones de acceso pueden cambiar; consulte la documentación de Kimi API de Moonshot.