Kimi K3.1 Pro API Tutorial: Erstelle einen selbstprüfenden 3D-CAD-Agenten in Python

Mit der Kimi K3.1 Pro API einen Image-to-CAD-Agenten bauen

Ein Image-to-CAD-Agent verwandelt Fotos eines Teils in ein CAD-Modell, das du bearbeiten kannst.

Warum Kimi K3.1 Pro und CadQuery für Image-to-CAD passen

Kimi K3.1 Pro kann vier Bilder lesen und dann auf das reagieren, was der eigene Code erzeugt. Der erwähnte Moonshot-Blog berichtet 92,7% mit Tools und 72.8% ohne bei BenchCADs Vision2Code-Aufgabe, die CAD-Code aus gerenderten Ansichten eines Teils bewertet. Die Zahlen stammen aus 1.000 Fällen bei max-Aufwand, und der Score mit Tools nutzte das Claude Code Harness, daher könnte ein Teil des Ergebnisses aufs Harness entfallen.

Das Benchmark sendet außerdem alle vier Ansichten als ein Bild und skaliert jedes Teil vor der Bewertung auf dieselbe Größe. Mein Setup schickt vier separate Ansichten plus ein echtes Maß bei high Aufwand. Nimm Moonshots Zahl daher als Anlass, den Test selbst zu fahren – nicht als Ergebnis. Als ich die Läufe machte, waren die offenen Gewichte noch nicht downloadbar.

CadQuery ist das Zielformat, weil ein CadQuery-Skript selbst ein parametrisches Modell ist. Ein Loch ist ein Aufruf mit Durchmesser und Position – eine spätere Änderung ändert eine Zahl, und der Körper baut sich neu. Eine STL-Datei liefert nur Dreiecke, und es gibt keine slot_width zum Anpassen.

Was der Agent sieht – und was verborgen bleibt

Kimi bekommt die vier Referenzbilder, die Breite von 60 mm und einen Systemprompt. Dieser legt Millimeter und Achsen fest, zentriert das Teil auf X und Y mit der Unterseite bei Z=0 und verlangt benannte Maße sowie einen finalen Solid in result.

Danach weiß Kimi nur, was die Tools melden. Die Kimi API führt CadQuery nicht aus, daher laufen alle vier Tools in der Anwendung:

• execute_cad führt ein Programm in einem Docker-Container ohne Netzwerk aus und speichert das Ergebnis als Kandidat

• inspect_cad meldet Validität, Anzahl der Solids, Bounding Box, Volumen und zylindrische Flächen

• render_cad rendert den Kandidaten aus denselben vier Kameras wie die Referenz

• submit_cad beendet eine Phase mit genau einem Kandidaten

Kimi sieht nie den Referenzcode oder einen Score. Der Evaluator liest die gespeicherten STEP-Dateien erst nach Abschluss des Agentenlaufs, ein Score kann den Agenten daher nicht steuern oder stoppen.

Scores fließen nie zurück zu Kimi. Bild: Autor.

Die Kimi K3.1 Pro API in Python einrichten

Um die Kimi K3.1 Pro API in Python zu nutzen, brauchst du vier Dinge. Ich habe alles auf Linux x86_64 mit folgenden Versionen getestet:

• Einen Kimi API-Schlüssel mit mindestens 1 $ Guthaben, gemäß dem K3.1 Pro Quickstart

• Python 3.12.3 mit openai 3.39.0, dem OpenAI SDK

• cadquery 2.8.0 zum Erstellen und Prüfen der Solids

• Docker 29.9.2 für die Sandbox

Die folgenden Snippets sind Auszüge aus dem vollständigen Projekt in diesem GitHub-Repository, das du als Nächstes klonst.

CadQuery installieren und die Docker-Sandbox bauen

Die Installationsanleitung von CadQuery bevorzugt conda, pip auf Python 3.12 funktioniert aber ebenfalls. Klone das Repository und richte es ein:

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             # dann deinen MOONSHOT_API_KEY eintragen
docker build -t cad-sandbox:2.8.0 sandbox/Bereitgestellt von

Das Sandbox-Image installiert dieselbe CadQuery-Version und läuft als normaler User. Docker setzt standardmäßig keine CPU- oder Speicherkontingente, siehe die Ressourcenlimits-Doku, daher setzt der Runner sie. Auf der Startseite des Repos stehen die Befehle zum Ausführen und Bewerten des Experiments – inklusive eines Pfads ohne API-Key oder Docker.

Bevor Kimis Code überhaupt den Container erreicht, versuch ihn selbst zu brechen. Mein Testprogramm versuchte, den API-Key zu lesen, ins Netzwerk zu gehen und außerhalb des Scratch-Ordners zu schreiben – alle drei Versuche wurden blockiert.

Drei geblockte Operationen in der Sandbox. Bild: Autor.

Deinen ersten Kimi K3.1 Pro API-Call machen

Das ist das reguläre OpenAI SDK, ausgerichtet auf Moonshots Endpoint. Setze reasoning_effort bei jeder Anfrage, denn ohne Angabe ist max Standard – und du kannst das Denken nicht abschalten.

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 oder max; API-Default ist max
    max_completion_tokens=2048,     # Reasoning und Antwort teilen sich dieses Limit
    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))Bereitgestellt von

Lass temperature, top_p, n und beide Penalties weg – im Quickstart stehen sie als fix. Selbst eine Ein-Satz-Antwort verbraucht den Großteil der Completion-Tokens fürs Reasoning, also dimensioniere das Limit entsprechend.

Eine Anfrage bestätigt Key und Modell. Bild: Autor.

Wenn die Kimi API neu für dich ist, deckt mein früheres Kimi K3 Tutorial Streaming, Tool-Calling, Caching und Vision-Input ab.

Ein Referenz-CAD-Modell und vier Testansichten erstellen

Ein Referenz-CAD-Modell ist dein Lösungsblatt, damit jede Bewertung einen exakten Vergleich hat. Ich habe meins vor der ersten Anfrage eingefroren – von den Kameras bis zu den Bewertungsregeln – und nach den Ergebnissen nichts mehr verändert.

Die Abmessungen der Halterung festlegen

Die Halterung ist ein L, das Stegblech ist hinten an die Grundplatte angesetzt. Der Ursprung liegt im Zentrum der Unterseite, mit X über die Breite, die Front in Richtung −Y und Z nach oben:

Ich habe die Lochreihe und den Schlitz jeweils mittig der Flächen platziert und 6,5 mm Löcher gewählt, ein gängiges M6-Spielmaß – so wäre es bei einer echten Halterung. Diese Wahl erwies sich als Schwachstelle dieses Teils, und gleich kommt das Warum.

In der Build-Funktion halten w, dep, h und t Breite, Tiefe, Höhe und Dicke. Dann werden die beiden Platten verbunden und die Features geschnitten:

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-Länge, Breite, Winkel
        .extrude(t, both=True))
result = base.union(upright).cut(holes).cut(slot)Bereitgestellt von

Das Skript prüft auf genau ein gültiges Solid in erwarteter Größe, bevor es eine STEP-Datei exportiert.

Vier Ansichten mit fixen Kameras rendern

Ein kleiner NumPy-Renderer zeichnet Front-, Top-, Rechts- und Isometrie-Ansichten mit derselben festen Rahmenwahl – für die Referenz und jeden Kandidaten. Bei 512 px entspricht ein Pixel etwa 0,19 mm, wobei Ablesungen aus dem Bild stärker abweichen können. Fixes Framing sorgt außerdem dafür, dass ein zu großes oder falsch platziertes Teil „falsch“ aussieht, statt neu zentriert zu werden.

Die vier Bilder, die an Kimi gehen. Bild: Autor.

Bewertungsregeln vor dem Agentenlauf festlegen

Der Evaluator misst das exportierte Solid – Parameternamen können ihn also nicht täuschen. Er schneidet jede STEP-Datei, um die Löcher, den Schlitz und beide Plattendicken zu finden, und berechnet Voxel-IoU, also den gemeinsamen Volumenanteil zweier Solids, auf einem 0,5-mm-Raster in echter Größe. Toleranzen folgen der Pixelskala: ±0,5 mm für Dicken, Lochdurchmesser und Schlitzbreite sowie ±1 bis ±1,5 mm für Längen und Positionen aus Bildern.

IoU allein reicht nicht. Ich finde die Zahl grob, nutze sie aber weiter, weil nichts Einfacheres zwei Solids vergleicht. Ein schlichtes L ohne Löcher und Schlitz erzielt immer noch über 0,96, und das richtige Teil um 20% zu groß skaliert auf perfekte 1,0, sobald beide auf dieselbe Größe gebracht werden.

Darum hat hier jeder Score 13 Pass/Fail-Checks daneben. Selbst 1,0 heißt nur, dass zwei Solids auf diesem Raster übereinstimmen – nicht auf jeden Mikrometer – und keine dieser Zahlen ist eine Fertigungsgarantie.

Aus Bildern CadQuery-Code mit Kimi K3.1 Pro erzeugen

Der erste Kandidat kommt aus einer einzigen Anfrage ohne Tools und läuft genau so, wie er zurückkam.

Vier Referenzansichten an die Kimi K3.1 Pro API senden

Kimis Vision-Input nimmt base64-Data-URLs in einem content-Array, öffentliche Bild-URLs akzeptiert es nicht. Der Systemprompt enthält die zuvor beschriebenen Frame- und Namensregeln, und die User-Nachricht trägt die vier PNGs und diesen 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.Bereitgestellt von

Die Anfrage selbst ist kurz:

images = [image_part(path) for path in view_paths]   # vier PNGs als 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,
)Bereitgestellt von

Um die Eingabegröße vor der Zahlung zu prüfen, schicke dieselben Messages an den Token-Schätzendpunkt – dessen Schätzung stimmte fast exakt mit der Rechnung überein. Vier 512px-Bilder liegen unter 2.000 Input-Tokens.

Das erste CadQuery-Programm in einer Sandbox ausführen

Der Runner schreibt den Code in einen Scratch-Ordner und startet einen Wegwerf-Container mit dem docker run-Befehl:

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)Bereitgestellt von

Im ersten Versuch dauerte Kimis Antwort etwa eine Minute. Das Programm benannte jede Dimension der versteckten Referenz – von bracket_depth = 40.0 bis slot_center_z = 25.5. Es erzeugte ein gültiges Solid und bestand alle Checks.

Gleiche Kamera, gleiche Skala, übereinstimmende Teile. Bild: Autor.

Ein perfekter erster Versuch ließ mich nach einem Leak suchen – aber die PNGs enthalten keine Metadaten, und kein Prompt trägt versteckte Werte. Kimis Code erklärt das Ergebnis: Wie erwähnt, sind die Features dort platziert, wo man sie als Designer setzen würde – genau so tat es Kimi.

Kimi leitet die Feature-Positionen aus Mittelpunkten ab. Bild: Autor.

Einen selbstprüfenden Tool-Calling-Agenten mit Kimi K3.1 Pro bauen

Ein Tool-Calling-Agent läuft in einer Schleife. Kimi fordert ein Tool an, dein Code führt es aus, und das Ergebnis geht als Tool-Message zurück, bis Kimi fertig ist.

Drei Phasen, jeweils mit harten Limits. Bild: Autor.

Tools zum Ausführen, Prüfen und Rendern von CAD definieren

Hier ist execute_cad als Schema. Es liefert ein kurzes Resultat in festem Format, inklusive der letzten Traceback-Zeilen bei Fehlern:

{"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"]}}}Bereitgestellt von

render_cad liefert seine vier Bilder direkt in der Tool-Message – dasselbe „nochmal hinschauen“-Muster wie unser Agentic-Vision-Tutorial mit Gemini. Kimis Doku zeigt dafür kein Beispiel, sieh es also als beobachtetes Verhalten. In allen drei Läufen trug eine role: "tool"-Message image_url-Teile, und das Modell las sie.

Die komplette Assistant-Message in der Tool-Schleife behalten

Drei Details sind hier wichtig, die ersten beiden kommen aus Kimis Leitfaden für Thinking-Modelle und dem Quickstart:

• Bei jeder Runde die komplette Assistant-Message zurücksenden – inklusive reasoning_content und tool_calls

• Pro Tool-Call genau eine Tool-Message hinzufügen – mit passender tool_call_id

• Die Message mit model_dump() serialisieren, da das OpenAI SDK kein typisiertes Feld reasoning_content hat

Die Schleife unten befolgt alle drei Punkte:

message = response.choices[0].message.model_dump(exclude_none=True)
messages.append(message)        # alles davon, sonst verliert die nächste Runde still ihr 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})Bereitgestellt von

Verlass dich hier nicht auf die API, um Fehler abzufangen. Eine Anfrage, aus der reasoning_content in der Historie entfernt wurde, funktioniert zwar – aber die Doku verlangt das Feld, und sein Weglassen kann spätere Runden beeinflussen. Mir wäre ein 400er lieber als ein stiller Fehler.

Das Budget liegt im Schleifen-Code, Kimi kann es nicht ändern. Sind die 3 Reparaturen aufgebraucht, antwortet execute_cad mit einem Fehler, und submit_cad lehnt alles außer genau einem gültigen Solid ab.

Was in der Reparaturphase passierte

Nicht viel – ich hätte diesen Abschnitt fast gestrichen. Ich habe die Reparaturschleife gebaut, in der Annahme, dass sie die Hauptarbeit übernimmt. Kimi hat sie kaum berührt: Es inspizierte seinen ersten Kandidaten, renderte ihn, schrieb eine selbstsichere Zusammenfassung, dass alle vier Referenzansichten passen, und reichte dasselbe Programm wieder ein.

Diese Zusammenfassung war nicht immer korrekt. In einem Lauf meldete inspect_cad einen Lochradius von 3,0 mm – also 6,0 mm Löcher, wo die Referenz 6,5 mm hat. Kimi reichte trotzdem ein. Ein halber Millimeter sind in diesen Ansichten weniger als 3 Pixel (dem würde ich mit bloßem Auge auch nicht trauen), und kein Feedback nannte den richtigen Durchmesser.

Das Tool meldete 3,0 mm Radien. Bild: Autor.

Ein parametrisches CAD-Modell mit Kimi K3.1 Pro bearbeiten

Weil die Reparaturschleife untätig blieb, war die Designänderung der aussagekräftigere Test. Er ist milde – eine Änderung, die zwei Features gleichzeitig verschiebt, würde deutlich härter fordern.

Kimi bitten, den Schlitz zu verbreitern

Die Bearbeitung setzt die gleiche Konversation fort und startet vom Kandidaten, den Kimi eingereicht hat – nicht von meinem Referenzcode:

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.Bereitgestellt von

Kimi nutzte eines der 3 erlaubten Programme. Der Diff ist eine Zeile, slot_width = 6.0 zu slot_width = 9.0, dann eine Runde fürs Inspizieren und Rendern und ein Submit.

Die Änderung an der exportierten Geometrie prüfen

Eine neue Zahl im Code beweist nicht, dass sich der Solid geändert hat. Der Evaluator verglich die Solids vor und nach der Änderung Voxel für Voxel und ignorierte nur den Bereich, den der breitere Schlitz belegen darf:

• Der Schlitz ist 9 mm breit, mit gleicher Länge und gleichem Zentrum
• Löcher, Plattendicke und Außenmaße sind unverändert
• Außerhalb des Schlitzbereichs hat sich kein Material verändert

Jeder Edit-Check bestand – jedes Mal.

Die Änderung funktionierte sauber, weil slot2D() seine Länge als End-to-End interpretiert – der Schlitz blieb 20 mm lang, und der gerade Abschnitt wurde kürzer. Ein Programm, das den Abstand der beiden Bogenmittelpunkte speichert, hätte den Schlitz um 3 mm verlängert.

Geändert wurde nur der Schlitz. Bild: Autor.

Wie genau war der Kimi K3.1 Pro CAD-Agent?

Der Agent bestand in allen drei Läufen jeden versteckten Check – innerhalb der vorab festgelegten Toleranzen. Die Tabelle dient als Recap:

Drei Läufe sind noch keine Erfolgsquote – nur ein Hinweis, dass das Ergebnis bei einer Halterung gehalten hat. Die 6,0 mm-Löcher in der Reparaturphase bestanden nur, weil sie genau an der ±0,5 mm-Toleranzgrenze für Löcher lagen – mit engerem Limit wäre dieser Lauf durchgefallen.

Selbstkorrektur hatte nichts zu tun

Der Test, der zeigen würde, ob die Schleife ein Modell verbessert, ist ein Fault-Injection-Lauf – der Agent startet mit einem Programm mit bekanntem Fehler. Das würde ich gesondert berichten.

Tokenkosten und Laufzeit pro Versuch

Jeder Lauf kostete 6,3 bis 7,3 Cent für sechs Requests und sieben Tool-Calls. Das sind nur API-Kosten – Rendern und Docker liefen auf meiner Maschine.

Bepreise jeden Request über seine usage-Felder zu den veröffentlichten Raten für kimi-k3.1-pro. Pro Million Tokens: 2,00 $ für Input, 10,00 $ für Output, 0,20 $ für Cache-Hits und 2,00 $ für 5-Minuten-Cache-Writes.

Die erste Anfrage kostet am meisten – dort denkt Kimi. Output macht über die Hälfte der Rechnung aus, und Cache-Writes 23% bis 35%, während Cache-Hits fast nichts kosten. So addieren sich die drei Input-Felder laut der verlinkten Chat-Completions-Referenz – du kannst es überspringen, wenn dein Tracker Cache-Writes schon gesondert ausweist:

uncached = u.prompt_tokens - cached - written   # die drei Teile summieren sich zu prompt_tokens
cost = (uncached * 2.00 + cached * 0.20 + written * 2.00 + u.completion_tokens * 10.00) / 1e6Bereitgestellt von

Reasoning-Tokens stecken bereits in completion_tokens – also nicht doppelt zählen. Ein 5-Minuten-Cache-Write kostet so viel wie un-cached Input, daher lohnt sich Prompt-Caching nur, wenn ein Präfix wieder gelesen wird. Tool-Schleifen senden jede Runde dieselbe Historie – hier senkte Caching die Input-Rechnung auf unter 40% des Plain-Preises.

Ein Lauf dauert rund drei Minuten – größtenteils Wartezeit –, weil der Client Anfragen wegen des Limits, das ich in den FAQs erkläre, im 21-Sekunden-Abstand schickt.

Wo KI-CAD aus Bildern an Grenzen stößt

Die Hauptgrenze ist: Bilder tragen nicht alle Maße. Mein Test fügt noch ein paar hinzu:

• Renderings zeigen keine Details unterhalb eines Pixels. Wenn ein Maß zählt, gib es als Text an oder miss es mit einem Tool.
• Die Halterung war leicht zu raten. Exzentrische Löcher und ungewöhnliche Maße würden zeigen, ob Kimi die Pixel liest – oder Designgewohnheiten.
• Docker-Flags blockieren nur, was sie benennen. Sie stoppten das fehlverhaltende Programm aus dem Setup, aber Model-Code kann dennoch seine volle Minute CPU verbrauchen. Unser Leitfaden zur Absicherung von KI-Agenten in Containern deckt die nächsten Schichten ab.
• Diese Checks sagen nichts über Festigkeit. Last, Material, die verrundete Innenecke eines echten Teils, Schraubenpassung und Toleranzketten liegen außerhalb dieses Tests.

Die einfache Halterung ist eher eine Begrenzung meines Tests als von Kimi.

Fazit

Wir haben einen Agenten gebaut, der aus vier Bildern parametrischen CadQuery-Code schreibt, sein Solid mit Tools prüft und auf Wunsch ein Feature editiert. Für diese Halterung ist die Antwort auf meine Eingangsfrage: ja. Alle drei Läufe bestanden auf die erste Anfrage – innerhalb meiner Toleranzen – und die Schlitzänderung ließ den Rest des Teils unberührt.

Für die Reparaturschleife kann ich nicht bürgen – Kimi fand nichts zu reparieren. Sein Review ließ den einmaligen 0,5 mm-Fehler durch, weil es nur Pixel sah, nie den wahren Durchmesser. Ich würde das Ergebnis nicht auf ein Teil mit Sondermaßen oder auf Fotos eines echten Teils verallgemeinern.

Was bleibt, ist die Methode: die Referenz verstecken, Bewertungsregeln vor der ersten Anfrage einfrieren und das exportierte Solid statt des Codes bewerten. Kimi sagte dreimal, sein Kandidat passe – und nur der Evaluator konnte unterscheiden, dass es zweimal exakt und einmal knapp richtig war. Den Evaluator würde ich beibehalten; ein Fault-Injection-Lauf wäre meine erste Erweiterung.

Mehr zum Anschluss von Modellen an eigene Tools findest du in unserem Developing AI Systems with the OpenAI API-Kurs – er behandelt Function Calling mit demselben SDK, das dieser Agent nutzt.