Kimi K3.1 Pro API‑handledning: Bygg en självkontrollerande 3D‑CAD‑agent i Python

Använd Kimi K3.1 Pro API för att bygga en bild‑till‑CAD‑agent

En bild‑till‑CAD‑agent omvandlar bilder av en detalj till en CAD‑modell som du kan redigera.

Varför Kimi K3.1 Pro och CadQuery passar bild‑till‑CAD

Kimi K3.1 Pro kan läsa fyra bilder och sedan reagera på vad dess egen kod producerar. Samma Moonshot‑blogg jag nämnde tidigare rapporterar 92,7% med verktyg och 72.8% utan på BenchCAD:s Vision2Code‑uppgift, som poängsätter CAD‑kod skriven från renderade vyer av en detalj. Dessa siffror kommer från ett urval på 1 000 fall med max ansträngning, och poängen med verktyg använde Claude Code harness, så en del av den poängen kan tillhöra harnessen.

Benchmarken skickar också alla fyra vyer i en bild och skalar varje detalj till samma storlek innan poängsättning. Min skickar fyra separata vyer plus en verklig dimension med high ansträngning, så ta Moonshots siffra som en anledning att köra testet snarare än som dess resultat. När jag körde dessa försök gick det ännu inte att ladda ner de öppna vikterna.

CadQuery är utdataformatet eftersom ett CadQuery‑skript i sig är en parametrisk modell. Ett hål är ett anrop med en diameter och en position, så en senare ändring ändrar ett tal och soliden byggs om. En STL‑fil ger dig trianglar, och det finns ingen slot_width att ändra.

Vad agenten ser och vad som förblir dolt

Kimi får de fyra referensbilderna, bredden 60 mm och en systemprompt. Den prompten låser millimeter och axlar, centrerar detaljen på X och Y med sin botten vid Z=0 och ber om namngivna dimensioner och en slutlig solid i result.

Efter det vet Kimi bara vad dess verktyg rapporterar. Kimi‑API:et kör inte CadQuery, så alla fyra verktygen finns i applikationen:

• execute_cad kör ett program i en Docker‑container utan nätverk och sparar resultatet som en kandidat

• inspect_cad rapporterar giltighet, antal solider, begränsningslåda, volym och cylindriska ytor

• render_cad ritar kandidaten från samma fyra kameror som referensen

• submit_cad avslutar en fas med en kandidat

Kimi ser aldrig referenskoden eller någon poäng. Utvärderaren läser endast sparade STEP‑filer efter att agenten är klar, så en poäng kan inte styra eller stoppa agenten.

Poäng flödar aldrig tillbaka till Kimi. Bild av författaren.

Ställ in Kimi K3.1 Pro API i Python

För att använda Kimi K3.1 Pro API i Python behöver du fyra saker. Jag testade allt på Linux x86_64 med dessa versioner:

• En Kimi‑API‑nyckel med minst $1 insatt, enligt K3.1 Pro quickstart

• Python 3.12.3 med openai 3.39.0, OpenAI‑SDK:t

• cadquery 2.8.0 för att bygga och kontrollera solider

• Docker 29.9.2 för sandboxen

Kodsnuttarna nedan är utdrag ur hela projektet i detta GitHub‑repo, som du klonar härnäst.

Installera CadQuery och bygg Docker‑sandboxen

CadQuerys installationsguide föredrar conda, även om pip på Python 3.12 också fungerar. Klona repot och ställ in det:

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/Drivs av

Sandbox‑imagen installerar samma CadQuery‑version och körs som en vanlig användare. Docker sätter inga CPU‑ eller minnesgränser som standard, enligt dess resursbegränsningsdokumentation, så köraren sätter dem. Repons framsida listar kommandon för att köra och poängsätta experimentet, inklusive en väg utan API‑nyckel eller Docker.

Innan Kimis kod når containern, försök bryta den själv. Mitt testprogram försökte läsa API‑nyckeln, nå nätverket och skriva utanför sin scratch‑mapp, och alla tre försöken misslyckades.

Tre blockerade operationer i sandboxen. Bild av författaren.

Gör ditt första anrop till Kimi K3.1 Pro API

Detta är det vanliga OpenAI‑SDK:t pekat mot Moonshots slutpunkt. Sätt reasoning_effort på varje begäran, för om du utelämnar det får du max, och du kan inte stänga av tänkandet.

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))Drivs av

Lämna temperature, top_p, n och båda påföljderna, som quickstarten listar som fasta. Även ett ensatsigt svar som detta spenderar merparten av sina completion‑tokens på resonemang, så dimensionera gränsen med det i åtanke.

En begäran bekräftar nyckel och modell. Bild av författaren.

Om Kimi‑API:et är nytt för dig täcker min tidigare Kimi K3‑handledning streaming, verktygsanrop, caching och syninmatning.

Skapa en referens‑CAD‑modell och fyra testvyer

En referens‑CAD‑modell är din facit, så varje poäng har något exakt att jämföra med. Jag låste min innan första begäran, från kamerorna till poängsättningsreglerna, och ändrade inget av det efter att ha sett resultat.

Definiera fästets dimensioner

Fästet är ett L, med den upprätta plåten förenad vid bakkanten av basen. Dess origo sitter i centrum av den nedersta ytan, med X över bredden, framsidan mot −Y och Z uppåt:

Jag lade hålraden och skåran mitt på sina respektive ytor och använde 6,5 mm hål, en vanlig M6‑frigång, eftersom ett riktigt fäste skulle göra det. Det valet visade sig vara den här detaljens svaghet, och vi kommer till varför.

Inuti byggfunktionen håller w, dep, h och t bredd, djup, höjd och tjocklek. Den fogar samman de två plåtarna och skär ut detaljerna:

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)Drivs av

Skriptet kontrollerar att en giltig solid med förväntad storlek finns innan det exporterar en STEP‑fil.

Rendera fyra vyer med fasta kameror

En liten NumPy‑renderer ritar fram-, topp-, höger- och isometriska vyer med samma fasta inramning för referensen och varje kandidat. Vid 512 px täcker en pixel cirka 0,19 mm, även om en avläsning från bilden kan ligga mer fel än så. Fast inramning gör också att en kandidat som är för stor eller felplacerad ser fel ut i stället för att centreras om.

De fyra bilderna som skickas till Kimi. Bild av författaren.

Sätt utvärderingsreglerna innan du kör agenten

Utvärderaren mäter den exporterade soliden, så parameternamn kan inte lura den. Den skivar varje STEP‑fil för att hitta hålen, skåran och båda plåttjocklekarna, och den beräknar voxel‑IoU, andelen volym två solider har gemensamt, på ett 0,5 mm rutnät i verklig storlek. Toleranserna följer pixelskalan: ±0,5 mm för tjocklekar, håldiametrar och skårebredd, och ±1 till ±1,5 mm för längder och positioner avlästa från bilder.

IoU räcker inte ensamt. Jag tycker det är en trubbig siffra, och jag fortsätter använda den eftersom inget enklare jämför två solider. Ett enkelt L utan hål och utan skåra ger fortfarande över 0,96, och rätt detalj som gjorts 20% för stor får perfekta 1,0 när båda skalas till samma storlek.

Därför kommer varje poäng här med 13 godkända eller underkända kontroller. Även en perfekt 1,0 betyder bara att två solider stämmer på det rutnätet, inte på mikronnivå, och ingen av dessa siffror är en tillverkningsgaranti.

Generera CadQuery‑kod från bilder med Kimi K3.1 Pro

Den första kandidaten kommer från en begäran utan verktyg, och den körs exakt som den returnerades.

Skicka fyra referensvyer till Kimi K3.1 Pro API

Kimis syninmatning tar base64‑data‑URL:er inuti en content‑array, och den accepterar inte publika bild‑URL:er. Systemprompten innehåller de inramnings‑ och namngivningsregler jag beskrev tidigare, och användarmeddelandet bär de fyra PNG:erna och denna 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.Drivs av

Själva begäran är kort:

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,
)Drivs av

För att kontrollera indata‑storleken innan du betalar, skicka samma meddelanden till tokenestimat‑slutpunkten, vars uppskattning nästan exakt matchade fakturan. Fyra bilder på 512 px blir under 2 000 indata‑tokens.

Kör det första CadQuery‑programmet i en sandbox

Köraren skriver koden till en scratch‑mapp och startar en engångscontainer med kommandot 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)Drivs av

I det första försöket tog Kimis svar ungefär en minut. Dess program namngav varje dimension i den dolda referensen, från bracket_depth = 40.0 till slot_center_z = 25.5. Det producerade en giltig solid och klarade varje kontroll.

Samma kamera, samma skala, matchande delar. Bild av författaren.

Ett perfekt första försök fick mig att leta efter ett läckage, men PNG:erna bär ingen metadata, och ingen prompt innehåller ett dolt värde. Kimis kod förklarar resultatet. Som jag nämnde när jag definierade fästet sitter detaljerna där en konstruktör skulle placera dem, och det gjorde Kimi också.

Kimi härleder detaljpositioner från mittpunkter. Bild av författaren.

Bygg en självkontrollerande verktygskallande agent med Kimi K3.1 Pro

En verktygskallande agent körs i en loop. Kimi ber om ett verktyg, din kod kör det och resultatet går tillbaka som ett verktygsmeddelande tills Kimi är klar.

Tre faser, var och en med hårda gränser. Bild av författaren.

Definiera verktyg för att köra, inspektera och rendera CAD

Här är execute_cad som schema. Det returnerar ett kort resultat i ett fast format, med de sista raderna av traceback när ett program misslyckas:

{"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"]}}}Drivs av

render_cad returnerar sina fyra bilder i själva verktygsmeddelandet, samma titta‑igen‑mönster som vår handledning om agentisk syn använder med Gemini. Kimis dokument visar inget exempel på detta, så betrakta det som observerat beteende. I alla tre försöken bar ett role: "tool" ‑meddelande image_url‑delar, och modellen läste dem.

Behåll hela assistentmeddelandet i verktygsloopen

Tre detaljer spelar roll här, och de två första kommer från Kimis guide för tänkande modeller och quickstart:

• Skicka tillbaka hela assistentmeddelandet varje vända, inklusive reasoning_content och tool_calls

• Lägg till ett verktygsmeddelande per verktygsanrop, med matchande tool_call_id

• Serialisera meddelandet med model_dump(), eftersom OpenAI‑SDK:t saknar ett typat reasoning_content‑fält

Loopen nedan följer alla tre:

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})Drivs av

Räkna inte med att API:et fångar ett misstag här. En begäran med reasoning_content borttaget från historiken lyckas fortfarande, även om dokumentationen kräver fältet och att ta bort det kan ändra hur senare vändor fortsätter. Jag skulle föredra en 400 framför en bugg som tyst misslyckas.

Budgeten ligger i loopens kod, där Kimi inte kan ändra den. När de tre reparationerna är förbrukade svarar execute_cad med ett fel, och submit_cad vägrar allt som inte är en giltig solid.

Vad som hände i reparationsfasen

Inte mycket, och jag var nära att stryka avsnittet av den anledningen. Jag byggde reparationsloopen i tron att den skulle göra det mesta av arbetet, och Kimi rörde den knappt. Den inspekterade sin första kandidat, renderade den, skrev en självsäker sammanfattning om att den matchade alla fyra referensvyer och skickade in samma program den började med.

Den sammanfattningen var inte alltid rätt. I ett försök rapporterade inspect_cad en hålradius på 3,0 mm, alltså 6,0 mm hål där referensen har 6,5 mm, och Kimi skickade ändå in. En halv millimeter är under 3 pixlar i dessa vyer (jag skulle inte lita på mina egna ögon i den storleken heller), och inget i återkopplingen sa vad rätt diameter var.

Verktyget rapporterade 3,0 mm radier. Bild av författaren.

Redigera en parametrisk CAD‑modell med Kimi K3.1 Pro

Med reparationsloopen vilande blev designändringen det mer avslöjande testet. Det är ett milt test, och en ändring som flyttar två detaljer samtidigt skulle pressa mycket hårdare.

Be Kimi att bredda skåran

Redigeringen fortsätter samma konversation och utgår från kandidaten Kimi skickade in, inte från min referenskod:

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.Drivs av

Kimi använde ett av sina tre tillåtna program. Diffen är en rad, slot_width = 6.0 till slot_width = 9.0, sedan en vända för att inspektera och rendera och en inlämning.

Kontrollera redigeringen på exporterad geometri

Ett nytt tal i koden bevisar inte att soliden ändrades. Utvärderaren jämförde soliderna före och efter redigeringen voxel för voxel och ignorerade endast det utrymme som den bredare skåran får ta:

• Skåran är 9 mm bred, med samma längd och centrum
• Hål, plåttjocklek och yttermått är oförändrade
• Inget material ändrades utanför skåreområdet

Varje redigeringskontroll passerade, varje gång.

Redigeringen fungerade rent eftersom slot2D() behandlar sin längd som ända till ända, så skåran förblev 20 mm lång och den raka delen blev kortare. Ett program som lagrade avståndet mellan de två bågcentrumen skulle ha gjort skåran 3 mm längre.

Redigeringen ändrade endast skåran. Bild av författaren.

Hur exakt var Kimi K3.1 Pro CAD‑agenten?

Agenten klarade varje dold kontroll i alla tre försöken, inom de toleranser jag låste i förväg. Läs tabellen som en sammanfattning:

Tre försök är ingen träffsäkerhet, bara en signal om att resultatet höll för ett fäste. De 6,0 mm hålen från reparationsfasen passerade endast för att de låg exakt på ±0,5 mm håltolerans, så en strängare gräns hade fällt det försöket.

Självkorrigeringen hade inget att fixa

Testet som skulle visa om loopen förbättrar en modell är en felinjektionskörning, som startar agenten från ett program med ett känt fel. Det skulle jag rapportera separat från dessa försök.

Tokenkostnad och körtid per försök

Varje försök kostade 6,3 till 7,3 cent för sex begäranden och sju verktygsanrop. Det är bara API‑avgifter, eftersom rendering och Docker kördes på min maskin.

Prissätt varje begäran från dess usage‑fält enligt de publicerade priserna för kimi-k3.1-pro. Per miljon tokens är det $2,00 för indata, $10,00 för utdata, $0,20 för cache‑träffar och $2,00 för 5‑minuters cache‑skrivningar.

Den första begäran kostar mest eftersom det är där Kimi resonerar. Utdata är mer än halva notan och cache‑skrivningar 23% till 35%, medan cache‑träffar kostar nästan ingenting. Så här summeras de tre indatafälten, enligt referensen för Chat Completions som jag länkade tidigare, och du kan hoppa över det om din spårare redan delar upp cache‑skrivningar:

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) / 1e6Drivs av

Resonemangstokens ingår redan i completion_tokens, så lägg inte till dem en andra gång. En 5‑minuters cache‑skrivning kostar samma som okachade indata, så prompt‑cache lönar sig bara när ett prefix läses tillbaka. Verktygsloopar skickar om samma historik varje vända, och här kapade caching indata‑notan till under 40% av grundpriset.

Ett försök tar cirka tre minuter, mest väntan, eftersom klienten sprider begäranden 21 sekunder isär för hastighetsgränsen jag tar upp i FAQ:en.

Var AI‑generering av CAD från bilder brister

Den stora begränsningen är att bilder inte kan bära varje mått. Mitt test lägger till några till:

• Renderingar kan inte visa detaljer mindre än en pixel. Om ett mått är viktigt, ge det som text eller mät det med ett verktyg.
• Fästet var lätt att gissa. Off‑center‑hål och udda storlekar skulle testa om Kimi läser pixlarna eller konstruktionsvanorna.
• Docker‑flaggor blockerar bara det de namnger. De stoppade det felaktiga programmet från installationsavsnittet, men modellkod kan fortfarande bränna sin fulla minut CPU. Vår guide om att säkra AI‑agenter i containrar täcker nästa lager.
• Att klara dessa kontroller säger inget om hållfasthet. Last, material, den rundade innerhörna en riktig detalj skulle behöva, bultpassning och hur toleranser summeras ligger utanför detta test.

Det enkla fästet är mer en begränsning i mitt test än i Kimi.

Avslutande tankar

Vi byggde en agent som skriver parametrisk CadQuery‑kod från fyra bilder, kontrollerar sin egen solid med verktyg och redigerar en detalj på begäran. För det här fästet är svaret på min inledande fråga ja. Alla tre försöken passerade på första begäran inom de toleranser jag satte, och skåreredigeringen lämnade resten av detaljen orörd.

Reparationsloopen är den del jag inte kan gå i god för, eftersom Kimi aldrig hittade något att reparera. Dess granskning släppte igenom det enda felet på 0,5 mm eftersom den såg pixlar, aldrig den sanna diametern. Jag skulle inte generalisera resultatet till en udda storlek eller till foton av en verklig detalj.

Det som bär över är metoden att dölja referensen, frysa poängsättningsreglerna före första begäran och poängsätta den exporterade soliden i stället för koden. Kimi sa att dess kandidat matchade tre gånger, och bara utvärderaren kunde avgöra att det var rätt två gånger och nära en gång. Den utvärderaren är vad jag skulle behålla, och en felinjektionskörning vore min första utvidgning.

För mer om att koppla modeller till dina egna verktyg, vår Developing AI Systems with the OpenAI API‑kors täcker funktionsanrop med samma SDK som den här agenten använder.