Tutorial de la API Kimi K3.1 Pro: crea un agente CAD 3D con autocheck en Python

Usa la API Kimi K3.1 Pro para crear un agente de imagen a CAD

Un agente de imagen a CAD convierte fotos de una pieza en un modelo CAD que puedes editar.

Por qué Kimi K3.1 Pro y CadQuery encajan con imagen a CAD

Kimi K3.1 Pro puede leer cuatro imágenes y luego reaccionar a lo que produce su propio código. El mismo blog de Moonshot que mencioné antes reporta un 92,7% con herramientas y un 72.8% sin ellas en la tarea Vision2Code de BenchCAD, que puntúa código CAD escrito a partir de vistas renderizadas de una pieza. Esas cifras provienen de un subconjunto de 1.000 casos con esfuerzo max, y la puntuación con herramientas usó el harness de Claude Code, por lo que parte de esa puntuación puede deberse al harness.

El benchmark también envía las cuatro vistas en una sola imagen y escala todas las piezas al mismo tamaño antes de puntuar. En mi caso envío cuatro vistas separadas más una cota real con esfuerzo high, así que toma la cifra de Moonshot como un motivo para ejecutar la prueba, no como su resultado. Cuando hice estas pruebas, los pesos abiertos aún no se podían descargar.

CadQuery es el formato de salida porque un script CadQuery es en sí mismo un modelo paramétrico. Un agujero es una llamada con un diámetro y una posición; un cambio posterior modifica un número y el sólido se reconstruye. Un archivo STL te da triángulos y no hay slot_width que cambiar.

Qué ve el agente y qué se mantiene oculto

Kimi recibe las cuatro imágenes de referencia, el ancho de 60 mm y un prompt del sistema. Ese prompt fija milímetros y ejes, centra la pieza en X e Y con su base en Z=0, y pide dimensiones con nombre y un sólido final en result.

A partir de ahí, Kimi solo sabe lo que informan sus herramientas. La API de Kimi no ejecuta CadQuery, así que las cuatro herramientas viven en la aplicación:

• execute_cad ejecuta un programa en un contenedor Docker sin red y guarda el resultado como candidato

• inspect_cad informa de validez, número de sólidos, caja envolvente, volumen y caras cilíndricas

• render_cad dibuja el candidato desde las mismas cuatro cámaras que la referencia

• submit_cad cierra una fase con un candidato

Kimi nunca ve el código de referencia ni ninguna puntuación. El evaluador solo lee los archivos STEP guardados cuando el agente termina, así que una puntuación no puede guiar ni detener al agente.

Las puntuaciones nunca vuelven a Kimi. Imagen del autor.

Configura la API Kimi K3.1 Pro en Python

Para usar la API Kimi K3.1 Pro en Python, necesitas cuatro cosas. Probé todo en Linux x86_64 con estas versiones:

• Una clave de API de Kimi con al menos 1 $ recargado, según el quickstart de K3.1 Pro

• Python 3.12.3 con openai 3.39.0, el SDK de OpenAI

• cadquery 2.8.0 para construir y comprobar sólidos

• Docker 29.9.2 para el sandbox

Los fragmentos siguientes son extractos del proyecto completo en este repositorio de GitHub, que clonarás a continuación.

Instala CadQuery y crea el sandbox de Docker

La guía de instalación de CadQuery recomienda conda, aunque pip con Python 3.12 también funciona. Clona el repositorio y configúralo:

git clone https://github.com/KhalidAbdelaty/Kimi_K3.1_Pro_API_Tutorial.git
cd Kimi_K3.1_Pro_API_Tutorial
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env             # then add your MOONSHOT_API_KEY
docker build -t cad-sandbox:2.8.0 sandbox/Con la tecnología de

La imagen del sandbox instala la misma versión de CadQuery y se ejecuta como usuario normal. Docker no fija límites de CPU ni memoria por defecto, según su documentación de límites de recursos, así que el runner los establece. La portada del repositorio lista los comandos para ejecutar y puntuar el experimento, incluido un camino sin clave de API ni Docker.

Antes de que el código de Kimi llegue al contenedor, intenta romperlo tú mismo. Mi programa de prueba trató de leer la clave de API, acceder a la red y escribir fuera de su carpeta temporal, y los tres intentos fallaron.

Tres operaciones bloqueadas en el sandbox. Imagen del autor.

Haz tu primera llamada a la API Kimi K3.1 Pro

Es el SDK normal de OpenAI apuntando al endpoint de Moonshot. Define reasoning_effort en cada petición, porque si lo omites, te da max y no puedes desactivar el razonamiento.

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1")

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    reasoning_effort="high",        # low, high, or max; the API default is max
    max_completion_tokens=2048,     # reasoning and answer share this cap
    messages=[{"role": "user", "content": "In one sentence, what does a STEP file store?"}],
)
print(response.choices[0].message.content)
print("usage:", response.usage.model_dump(exclude_none=True))Con la tecnología de

Omite temperature, top_p, n y ambas penalizaciones, que el quickstart indica como fijas. Incluso una respuesta de una frase gasta la mayor parte de sus tokens de completion en razonamiento, así que dimensiona el límite con eso en mente.

Una petición confirma clave y modelo. Imagen del autor.

Si la API de Kimi es nueva para ti, mi tutorial de Kimi K3 anterior cubre transmisión, llamadas a herramientas, caché y entrada de visión.

Crea un modelo CAD de referencia y cuatro vistas de prueba

Un modelo CAD de referencia es tu plantilla de corrección, para que cada puntuación tenga algo exacto con lo que compararse. Cerré el mío antes de la primera petición, desde las cámaras hasta las reglas de evaluación, y no cambié nada después de ver resultados.

Define las dimensiones de la escuadra

La escuadra es una L, con el ala vertical unida en la parte trasera de la base. Su origen está en el centro de la cara inferior, con X a lo ancho, el frente hacia −Y y Z hacia arriba:

Situé la fila de agujeros y la ranura en el centro de sus caras y usé agujeros de 6,5 mm, una holgura M6 habitual, como tendría una escuadra real. Esa decisión resultó ser el punto débil de esta pieza; luego veremos por qué.

Dentro de la función de construcción, w, dep, h y t guardan ancho, profundidad, altura y espesor. Une las dos placas y recorta las características:

base = cq.Workplane("XY").box(w, dep, t, centered=(True, True, False))
upright = cq.Workplane("XY").center(0, dep / 2 - t / 2).box(w, t, h, centered=(True, True, False))
holes = cq.Workplane("XY").pushPoints([(-17, -3), (17, -3)]).circle(3.25).extrude(t)
slot = (cq.Workplane("XZ", origin=(0, dep / 2 - t / 2, 0)).center(0, 25.5)
        .slot2D(20, 6, 90)            # end-to-end length, width, angle
        .extrude(t, both=True))
result = base.union(upright).cut(holes).cut(slot)Con la tecnología de

El script comprueba que haya un sólido válido del tamaño esperado antes de exportar un STEP.

Renderiza cuatro vistas con cámaras fijas

Un pequeño renderizador con NumPy dibuja las vistas frontal, superior, derecha e isométrica con el mismo encuadre fijo para la referencia y cada candidato. A 512 px, un píxel cubre unos 0,19 mm, aunque una lectura desde la imagen puede desviarse más. El encuadre fijo también hace que un candidato demasiado grande o mal posicionado se vea mal en lugar de recentrarse.

Las cuatro imágenes que se envían a Kimi. Imagen del autor.

Fija las reglas de evaluación antes de ejecutar el agente

El evaluador mide el sólido exportado, así que los nombres de parámetros no pueden engañarlo. Corta cada archivo STEP para encontrar los agujeros, la ranura y ambos espesores de placa, y calcula el IoU de vóxeles, la fracción de volumen que dos sólidos tienen en común, en una malla de 0,5 mm a tamaño real. Las tolerancias siguen la escala de píxel: ±0,5 mm para espesores, diámetros de agujeros y ancho de ranura, y entre ±1 y ±1,5 mm para longitudes y posiciones leídas de imágenes.

El IoU por sí solo no basta. Me parece un número tosco, y lo sigo usando porque no hay nada más simple para comparar dos sólidos. Una L simple sin agujeros ni ranura aún puntúa por encima de 0,96, y la pieza correcta escalada un 20% demasiado grande puntúa 1,0 perfecto una vez que ambas se escalan al mismo tamaño.

Por eso cada puntuación aquí viene con 13 comprobaciones de aprobado o suspenso. Incluso un 1,0 perfecto solo significa que dos sólidos coinciden en esa malla, no al micrón, y ninguna de estas cifras es garantía de fabricación.

Genera código CadQuery a partir de imágenes con Kimi K3.1 Pro

El primer candidato sale de una sola petición sin herramientas y se ejecuta tal cual llega.

Envía cuatro vistas de referencia a la API Kimi K3.1 Pro

La entrada de visión de Kimi acepta URLs de datos base64 dentro de un array content, y no admite URLs públicas de imágenes. El prompt del sistema contiene el encuadre y las reglas de nombres que describí antes, y el mensaje del usuario lleva los cuatro PNG y este prompt:

These four images show one mechanical part, a bracket. Each view uses orthographic
projection, and all four use the same scale. The camera for each view is written at the
top of the image, and a small axis triad sits in the lower-left corner.

The overall width of the part along X is 60 mm. No other dimension is given, so estimate
the rest from the images.

Write one CadQuery program that rebuilds this part as an editable parametric model.
Return the complete program in a single python code block.Con la tecnología de

La petición en sí es corta:

images = [image_part(path) for path in view_paths]   # four PNGs as base64 data URLs
messages.append({"role": "user", "content": images + [{"type": "text", "text": BASELINE_PROMPT}]})
response = client.chat.completions.create(
    model="kimi-k3.1-pro", reasoning_effort="high",
    max_completion_tokens=32_768, messages=messages,
)Con la tecnología de

Para comprobar el tamaño de entrada antes de pagar, envía los mismos mensajes al endpoint de estimación de tokens, cuya estimación cuadró casi exactamente con la factura. Cuatro imágenes de 512 px suman menos de 2.000 tokens de entrada.

Ejecuta el primer programa CadQuery en un sandbox

El runner escribe el código en una carpeta temporal e inicia un contenedor desechable con el comando docker run:

cmd = ["docker", "run", "--rm", "--network", "none", "--read-only",
       "--tmpfs", "/tmp:size=64m", "--cap-drop", "ALL",
       "--security-opt", "no-new-privileges",
       "--memory", "1g", "--cpus", "1", "--pids-limit", "128",
       "-v", f"{work}:/work", "cad-sandbox:2.8.0"]
subprocess.run(cmd, capture_output=True, text=True, timeout=60)Con la tecnología de

En la primera prueba, la respuesta de Kimi tardó alrededor de un minuto. Su programa nombró cada dimensión de la referencia oculta, desde bracket_depth = 40.0 hasta slot_center_z = 25.5. Produjo un sólido válido y pasó todas las comprobaciones.

Misma cámara, misma escala, piezas que coinciden. Imagen del autor.

Un primer intento perfecto me hizo comprobar si había fuga, pero los PNG no llevan metadatos y ningún prompt contiene valores ocultos. El propio código de Kimi explica el resultado. Como comenté al definir la escuadra, las características están donde las colocaría una persona diseñadora, y Kimi hizo lo mismo.

Kimi deriva posiciones a partir de puntos medios. Imagen del autor.

Crea un agente con autocheck y tool-calling con Kimi K3.1 Pro

Un agente de llamadas a herramientas funciona en bucle. Kimi pide una herramienta, tu código la ejecuta y el resultado vuelve como mensaje de herramienta hasta que Kimi termina.

Tres fases, cada una con límites estrictos. Imagen del autor.

Define herramientas para ejecutar, inspeccionar y renderizar CAD

Aquí tienes execute_cad como esquema. Devuelve un resultado breve con un formato fijo, con las últimas líneas del traceback cuando un programa falla:

{"type": "function", "function": {
    "name": "execute_cad",
    "description": "Run a complete CadQuery program in an isolated sandbox. Returns a "
                   "candidate id, whether it ran, and a short error if it did not.",
    "parameters": {"type": "object", "properties": {
        "code": {"type": "string",
                 "description": "The complete program. It must assign the final solid to result."}},
        "required": ["code"]}}}Con la tecnología de

render_cad devuelve sus cuatro imágenes dentro del propio mensaje de herramienta, el mismo patrón de mirar de nuevo que usa nuestro tutorial de visión con agentes con Gemini. Los docs de Kimi no muestran un ejemplo de esto, así que tómalo como comportamiento observado. En las tres pruebas, un role: "tool" llevó partes image_url, y el modelo las leyó.

Mantén todo el mensaje del asistente en el bucle de herramientas

Hay tres detalles clave, y los dos primeros vienen de la guía de modelos con razonamiento y del quickstart de Kimi:

• Envía el mensaje completo del asistente en cada turno, incluidos reasoning_content y tool_calls

• Añade un mensaje de herramienta por cada llamada, con el tool_call_id correspondiente

• Serializa el mensaje con model_dump(), porque el SDK de OpenAI no tiene un campo tipado reasoning_content

El bucle siguiente sigue los tres puntos:

message = response.choices[0].message.model_dump(exclude_none=True)
messages.append(message)        # all of it, or the next turn quietly loses its reasoning
for call in message.get("tool_calls") or []:
    content = run_tool(call["function"]["name"], json.loads(call["function"]["arguments"]))
    messages.append({"role": "tool", "tool_call_id": call["id"], "content": content})Con la tecnología de

No confíes en que la API detecte un fallo aquí. Una petición con reasoning_content eliminado del historial sigue funcionando, aunque la documentación exija el campo y quitarlo puede cambiar cómo continúan los turnos. Preferiría un 400 a un bug silencioso.

El presupuesto vive en el código del bucle, donde Kimi no puede cambiarlo. Una vez que se usan las 3 reparaciones, execute_cad responde con un error, y submit_cad rechaza todo lo que no sea un sólido válido.

Qué pasó en la fase de reparación

Poca cosa, y casi elimino esta sección por eso. Construí el bucle de reparación esperando que hiciera la mayor parte del trabajo y Kimi casi no lo tocó. Inspeccionó su primer candidato, lo renderizó, escribió un resumen confiado diciendo que coincidía con las cuatro vistas de referencia y envió el mismo programa con el que empezó.

Ese resumen no siempre fue correcto. En una prueba, inspect_cad informó de un radio de agujero de 3,0 mm, o sea, agujeros de 6,0 mm donde la referencia tiene 6,5 mm, y Kimi lo envió igualmente. Medio milímetro son menos de 3 píxeles en estas vistas (yo tampoco me fiaría a ojo a ese tamaño), y nada en el feedback decía cuál era el diámetro correcto.

La herramienta informó radios de 3,0 mm. Imagen del autor.

Edita un modelo CAD paramétrico con Kimi K3.1 Pro

Con el bucle de reparación inactivo, el cambio de diseño fue la prueba más reveladora. Es una prueba suave, eso sí; un cambio que moviera dos características a la vez exigiría mucho más.

Pide a Kimi que ensanche la ranura

La edición continúa en la misma conversación y parte del candidato que Kimi envió, no de mi código de referencia:

Increase the width of the vertical slot in the upright plate from 6 mm to 9 mm. 
Keep the slot's center position and its end-to-end length as they are in your model. 
Do not change the mounting holes, the plate thickness, or the outer dimensions.Con la tecnología de

Kimi usó uno de sus 3 programas permitidos. El diff es de una línea, de slot_width = 6.0 a slot_width = 9.0, luego un turno para inspeccionar y renderizar y un submit.

Comprueba la edición en la geometría exportada

Un número nuevo en el código no prueba que el sólido haya cambiado. El evaluador comparó los sólidos antes y después de la edición vóxel a vóxel, ignorando solo el espacio que puede ocupar la ranura más ancha:

• La ranura tiene 9 mm de ancho, con la misma longitud y centro
• Agujeros, espesor de placa y dimensiones exteriores no cambiaron
• No cambió material fuera del área de la ranura

Todas las comprobaciones de la edición pasaron, siempre.

La edición funcionó limpia porque slot2D() trata su longitud como de extremo a extremo, así que la ranura siguió midiendo 20 mm y la parte recta se acortó. Un programa que guardara la distancia entre los centros de los arcos la habría alargado 3 mm.

La edición solo cambió la ranura. Imagen del autor.

¿Qué precisión tuvo el agente CAD de Kimi K3.1 Pro?

El agente pasó todas las comprobaciones ocultas en las tres pruebas, dentro de las tolerancias que fijé de antemano. Lee la tabla como un resumen:

Tres pruebas no son una tasa de acierto, solo una señal de que el resultado se mantuvo en una escuadra. Los agujeros de 6,0 mm de la fase de reparación pasaron porque estaban justo en el límite de ±0,5 mm para agujeros; con un umbral más estricto, esa prueba habría fallado.

La autocorrección no tuvo nada que arreglar

La prueba que mostraría si el bucle mejora un modelo sería una ejecución con error inyectado, que hace empezar al agente desde un programa con un fallo conocido. Lo contaría aparte de estas pruebas.

Coste en tokens y tiempo por prueba

Cada prueba costó entre 6,3 y 7,3 céntimos por seis peticiones y siete llamadas a herramientas. Solo son cargos de API; los renders y Docker se ejecutaron en mi máquina.

Calcula el precio de cada petición con los campos usage a las tarifas publicadas para kimi-k3.1-pro. Por millón de tokens: 2,00 $ de entrada, 10,00 $ de salida, 0,20 $ por aciertos de caché y 2,00 $ por escrituras de caché de 5 minutos.

La primera petición cuesta más porque ahí es donde Kimi razona. La salida es más de la mitad de la factura y las escrituras de caché suponen entre el 23% y el 35%, mientras que los aciertos apenas cuestan. Así se suman los tres campos de entrada, según la referencia de Chat Completions que enlacé antes; puedes omitirlo si tu tracker ya separa las escrituras de caché:

uncached = u.prompt_tokens - cached - written   # the three parts sum to prompt_tokens
cost = (uncached * 2.00 + cached * 0.20 + written * 2.00 + u.completion_tokens * 10.00) / 1e6Con la tecnología de

Los tokens de razonamiento ya están dentro de completion_tokens, así que no los sumes dos veces. Una escritura de caché de 5 minutos cuesta lo mismo que la entrada sin caché, por lo que el caché de prompt solo compensa cuando se vuelve a leer un prefijo. Los bucles de herramientas reenvían el mismo historial cada turno, y aquí la caché redujo la factura de entrada a menos del 40% de la tarifa normal.

Una prueba tarda unos tres minutos, sobre todo esperando, porque el cliente separa las peticiones 21 segundos por el límite de velocidad que cubriré en las FAQs.

Dónde flojea la generación de CAD por IA a partir de imágenes

El principal límite es que las imágenes no pueden llevar todas las cotas. Mi prueba añade algunos más:

• Los renders no muestran detalles menores que un píxel. Si una dimensión importa, indícala en texto o mídela con una herramienta.
• La escuadra era fácil de adivinar. Agujeros descentrados y medidas raras pondrían a prueba si Kimi lee los píxeles o los hábitos de diseño.
• Las flags de Docker solo bloquean lo que nombran. Pararon el programa díscolo de la sección de preparación, pero el código del modelo aún puede consumir su minuto completo de CPU. Nuestra guía para asegurar agentes de IA en contenedores cubre las siguientes capas.
• Superar estas comprobaciones no dice nada sobre resistencia. Carga, material, el redondeo interior que necesitaría una pieza real, el ajuste de los pernos y cómo suman las tolerancias quedan fuera de esta prueba.

La escuadra sencilla es más un límite de mi prueba que de Kimi.

Reflexiones finales

Hemos construido un agente que escribe código paramétrico en CadQuery a partir de cuatro imágenes, comprueba su propio sólido con herramientas y edita una característica a petición. Para esta escuadra, la respuesta a mi pregunta inicial es sí. Las tres pruebas pasaron a la primera dentro de las tolerancias que fijé, y la edición de la ranura no afectó al resto de la pieza.

El bucle de reparación es la parte que no puedo avalar, ya que Kimi no encontró nada que reparar. Su revisión dejó pasar el único error de 0,5 mm porque vio píxeles, nunca el diámetro real. No generalizaría el resultado a una pieza con medidas raras o a fotos de una real.

Lo que sí trasladaría es el método: ocultar la referencia, congelar las reglas de evaluación antes de la primera petición y puntuar el sólido exportado en lugar del código. Kimi dijo que su candidato coincidía tres veces, y solo el evaluador pudo decir que acertó dos y se quedó cerca una. Ese evaluador es lo que mantendría, y una ejecución con fallos inyectados sería mi primera ampliación.

Para más sobre cómo conectar modelos a tus propias herramientas, nuestro curso Developing AI Systems with the OpenAI API cubre function calling con el mismo SDK que usa este agente.