Tutorial da API Kimi K3.1 Pro: construa um agente 3D de CAD com auto-checagem em Python

Use a API Kimi K3.1 Pro para criar um agente image-to-CAD

Um agente image-to-CAD transforma imagens de uma peça em um modelo CAD que você pode editar.

Por que Kimi K3.1 Pro e CadQuery combinam com image-to-CAD

O Kimi K3.1 Pro consegue ler quatro imagens e reagir ao que o próprio código produz. O mesmo blog da Moonshot que citei relata 92,7% com ferramentas e 72.8% sem no Vision2Code do BenchCAD, que avalia código CAD escrito a partir de visões renderizadas de uma peça. Esses números vêm de um subconjunto de 1.000 casos com esforço max, e a pontuação com ferramentas usou o harness do Claude Code, então parte desse resultado pode ser mérito do harness.

O benchmark também envia as quatro vistas em uma única imagem e escala todas as peças para o mesmo tamanho antes de pontuar. No meu teste, envio quatro vistas separadas mais uma dimensão real com esforço high, então encare o número da Moonshot como um motivo para rodar o teste — não como o resultado final. Quando rodei estes ensaios, os pesos open não estavam disponíveis para download.

CadQuery é o formato de saída porque um script CadQuery já é um modelo paramétrico. Um furo é uma chamada com diâmetro e posição, então uma edição futura altera um número e o sólido é reconstruído. Um arquivo STL entrega triângulos — não existe slot_width para mudar.

O que o agente vê e o que fica oculto

O Kimi recebe as quatro imagens de referência, a largura de 60 mm e um prompt de sistema. Esse prompt fixa milímetros e os eixos, centraliza a peça em X e Y com a base em Z=0 e pede dimensões nomeadas e um sólido final em result.

Depois disso, o Kimi só sabe o que suas ferramentas reportam. A API do Kimi não executa CadQuery, então as quatro ferramentas vivem no aplicativo:

• execute_cad executa um programa em um contêiner Docker sem rede e salva o resultado como candidato

• inspect_cad informa validade, contagem de sólidos, bounding box, volume e faces cilíndricas

• render_cad renderiza o candidato das mesmas quatro câmeras da referência

• submit_cad encerra uma fase com um candidato

O Kimi nunca vê o código de referência nem qualquer pontuação. O avaliador só lê arquivos STEP salvos depois que o agente termina, então uma nota não pode direcionar nem interromper o agente.

As pontuações nunca voltam para o Kimi. Imagem do autor.

Configure a API Kimi K3.1 Pro em Python

Para usar a API Kimi K3.1 Pro em Python, você precisa de quatro itens. Testei tudo no Linux x86_64 com estas versões:

• Uma chave de API do Kimi com pelo menos US$ 1 de crédito, conforme o quickstart do K3.1 Pro

• Python 3.12.3 com openai 3.39.0, o SDK da OpenAI

• cadquery 2.8.0 para construir e checar sólidos

• Docker 29.9.2 para o sandbox

Os trechos abaixo são excertos do projeto completo neste repositório no GitHub, que você vai clonar a seguir.

Instale o CadQuery e construa o sandbox no Docker

O guia de instalação do CadQuery prefere conda, embora pip no Python 3.12 também funcione. Clone o repositório e configure:

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             # então adicione sua MOONSHOT_API_KEY
docker build -t cad-sandbox:2.8.0 sandbox/Tecnologia

A imagem do sandbox instala a mesma versão do CadQuery e roda como usuário regular. O Docker não aplica limites de CPU ou memória por padrão, conforme a documentação de restrições de recursos, então o runner define esses limites. A página inicial do repositório lista os comandos para executar e pontuar o experimento — inclusive um caminho sem chave de API nem Docker.

Antes do código do Kimi chegar ao contêiner, tente você mesmo quebrá-lo. Meu programa de teste tentou ler a chave da API, acessar a rede e gravar fora da pasta temporária — e todas as três tentativas falharam.

Três operações bloqueadas no sandbox. Imagem do autor.

Faça sua primeira chamada à API Kimi K3.1 Pro

É o SDK padrão da OpenAI apontado para o endpoint da Moonshot. Defina reasoning_effort em toda requisição, porque se deixar de fora o valor será max e você não consegue desligar o raciocínio.

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 ou max; o padrão da API é max
    max_completion_tokens=2048,     # raciocínio e resposta compartilham este teto
    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))Tecnologia

Deixe de fora temperature, top_p, n e as duas penalidades, que o quickstart lista como fixas. Mesmo uma resposta de uma frase gasta a maior parte dos tokens de completion em raciocínio, então ajuste o teto considerando isso.

Uma requisição confirma chave e modelo. Imagem do autor.

Se a API do Kimi é nova para você, meu tutorial do Kimi K3 anterior cobre streaming, chamadas de ferramenta, caching e entrada de visão.

Crie um modelo CAD de referência e quatro vistas de teste

Um modelo CAD de referência é seu gabarito — assim toda avaliação tem algo exato para comparar. Eu congelei a referência antes da primeira requisição, das câmeras às regras de pontuação, e não mudei nada depois de ver resultados.

Defina as dimensões do suporte

O suporte é um L, com a aba vertical unida ao fundo da base. A origem fica no centro da face inferior, com X na largura, a frente para −Y e Z para cima:

Coloquei a linha de furos e a ranhura no meio de suas faces e usei furos de 6,5 mm, uma folga comum para M6 — como seria em um suporte real. Essa escolha acabou sendo o ponto fraco deste suporte — já já eu explico.

Dentro da função de construção, w, dep, h e t guardam a largura, profundidade, altura e espessura. Ela une as duas chapas e corta os recursos:

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)            # comprimento ponta a ponta, largura, ângulo
        .extrude(t, both=True))
result = base.union(upright).cut(holes).cut(slot)Tecnologia

O script checa se há um sólido válido do tamanho esperado antes de exportar um arquivo STEP.

Renderize quatro vistas com câmeras fixas

Um pequeno renderizador em NumPy gera vistas frontal, superior, direita e isométrica com o mesmo enquadramento fixo para a referência e para cada candidato. Em 512 px, um pixel cobre cerca de 0,19 mm, embora uma leitura pela imagem possa errar além disso. O enquadramento fixo também faz um candidato grande demais ou fora de lugar parecer errado, em vez de recentrado.

As quatro imagens enviadas ao Kimi. Imagem do autor.

Defina as regras de avaliação antes de rodar o agente

O avaliador mede o sólido exportado, então nomes de parâmetros não o enganam. Ele fatia cada arquivo STEP para encontrar os furos, a ranhura e as duas espessuras de chapa, e calcula o voxel IoU — a fração de volume comum entre dois sólidos — em uma grade de 0,5 mm no tamanho real. As tolerâncias seguem a escala do pixel: ±0,5 mm para espessuras, diâmetros de furos e largura da ranhura; e ±1 a ±1,5 mm para comprimentos e posições lidos em imagem.

IoU sozinho não basta. É um número meio grosseiro, e eu continuo usando porque nada mais simples compara dois sólidos. Um L simples sem furos nem ranhura ainda marca acima de 0,96, e a peça certa 20% maior marca 1,0 perfeito quando ambas são escaladas para o mesmo tamanho.

Por isso toda pontuação aqui vem com 13 verificações de aprovado/reprovado. Mesmo um 1,0 perfeito só quer dizer que dois sólidos batem naquela grade — não em cada mícron — e nenhum desses números é garantia de fabricação.

Gere código CadQuery a partir de imagens com o Kimi K3.1 Pro

O primeiro candidato vem de uma única requisição sem ferramentas, e roda exatamente como retornado.

Envie quatro vistas de referência para a API Kimi K3.1 Pro

A entrada de visão do Kimi recebe URLs de dados base64 dentro de um array content, e não aceita URLs públicos de imagem. O prompt de sistema traz as regras de enquadramento e nomeação que descrevi, e a mensagem do usuário leva os quatro PNGs e 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.Tecnologia

A requisição em si é curta:

images = [image_part(path) for path in view_paths]   # quatro PNGs como data URLs base64
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,
)Tecnologia

Para conferir o tamanho da entrada antes de pagar, envie as mesmas mensagens para o endpoint de estimativa de tokens, cuja estimativa bateu quase exatamente com a cobrança. Quatro imagens de 512 px ficam abaixo de 2.000 tokens de entrada.

Execute o primeiro programa CadQuery em um sandbox

O runner grava o código em uma pasta temporária e inicia um contêiner descartável com o 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)Tecnologia

No primeiro ensaio, a resposta do Kimi levou cerca de um minuto. O programa nomeou todas as dimensões da referência oculta, de bracket_depth = 40.0 a slot_center_z = 25.5. Produziu um sólido válido e passou em todas as verificações.

Mesma câmera, mesma escala, peças equivalentes. Imagem do autor.

Um acerto perfeito de primeira me fez procurar vazamento, mas os PNGs não têm metadata e nenhum prompt contém valores ocultos. O código do Kimi explica o resultado: como comentei ao definir o suporte, os recursos ficam onde um projetista colocaria — e o Kimi fez o mesmo.

Kimi deriva posições a partir de pontos médios. Imagem do autor.

Crie um agente com auto-checagem e chamadas de ferramenta com o Kimi K3.1 Pro

Um agente de chamada de ferramentas roda em loop. O Kimi pede uma ferramenta, seu código a executa, e o resultado volta como mensagem de ferramenta até o Kimi encerrar.

Três fases, cada uma com limites rígidos. Imagem do autor.

Defina ferramentas para executar, inspecionar e renderizar o CAD

Aqui está o execute_cad como esquema. Ele retorna um resultado curto em formato fixo, com as últimas linhas do traceback quando um programa falha:

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

render_cad devolve suas quatro imagens dentro da própria mensagem da ferramenta — o mesmo padrão de "olhar de novo" do nosso tutorial de visão agentic com o Gemini. A documentação do Kimi não mostra exemplo disso, então trate como comportamento observado. Nos três ensaios, uma mensagem com role: "tool" carregou partes image_url, e o modelo leu.

Mantenha a mensagem completa do assistant no loop de ferramentas

Três detalhes importam aqui — os dois primeiros vêm do guia de modelos de raciocínio do Kimi e do quickstart:

• Envie a mensagem completa do assistant a cada turno, incluindo reasoning_content e tool_calls

• Adicione uma mensagem de ferramenta por chamada de ferramenta, com o tool_call_id correspondente

• Serialize a mensagem com model_dump(), porque o SDK da OpenAI não tem campo tipado reasoning_content

O loop abaixo segue os três pontos:

message = response.choices[0].message.model_dump(exclude_none=True)
messages.append(message)        # tudo, ou o próximo turno perde o raciocínio em silêncio
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})Tecnologia

Não conte com a API para captar erro aqui. Uma requisição sem o reasoning_content no histórico ainda é aceita, embora a documentação peça o campo — e removê-lo pode alterar como os turnos seguintes continuam. Eu preferiria um 400 a um bug silencioso.

O orçamento fica no código do loop — fora do alcance do Kimi. Depois de usar os 3 reparos, execute_cad responde com erro, e submit_cad recusa qualquer coisa que não seja um sólido válido.

O que aconteceu na fase de reparo

Quase nada — e eu quase cortei esta seção por isso. Eu criei o loop de reparo esperando que ele fizesse grande parte do trabalho, e o Kimi mal tocou nele. Inspecionou o primeiro candidato, renderizou, escreveu um resumo confiante dizendo que batia com as quatro vistas de referência e submeteu o mesmo programa inicial.

Esse resumo nem sempre estava certo. Em um dos testes, o inspect_cad reportou raio de 3,0 mm para os furos — ou seja, 6,0 mm de diâmetro, enquanto a referência tem 6,5 mm —, e o Kimi submeteu mesmo assim. Meio milímetro dá menos de 3 pixels nessas vistas (eu também não confiaria no olho nessa escala), e nada no feedback dizia qual era o diâmetro correto.

A ferramenta reportou raios de 3,0 mm. Imagem do autor.

Edite um modelo CAD paramétrico com o Kimi K3.1 Pro

Com o loop de reparo ocioso, a mudança de design virou o teste mais interessante. Ainda é um teste leve — uma alteração que movesse dois recursos ao mesmo tempo exigiria bem mais.

Peça ao Kimi para alargar a ranhura

A edição continua a mesma conversa e parte do candidato submetido pelo Kimi — não do meu código de referência:

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.Tecnologia

O Kimi usou um dos 3 programas permitidos. O diff foi uma linha, de slot_width = 6.0 para slot_width = 9.0, depois um turno para inspecionar e renderizar, e em seguida a submissão.

Cheque a edição na geometria exportada

Um número novo no código não prova que o sólido mudou. O avaliador comparou os sólidos antes e depois voxel a voxel, ignorando apenas o espaço que a ranhura mais larga pode ocupar:

• A ranhura ficou com 9 mm de largura, com o mesmo comprimento e centro
• Furos, espessura das chapas e dimensões externas não mudaram
• Nenhum material mudou fora da área da ranhura

Todas as checagens da edição passaram, sempre.

A edição funcionou certinho porque o slot2D() trata seu comprimento como ponta a ponta — então a ranhura ficou com 20 mm e a parte reta encurtou. Um programa que guardasse a distância entre os centros dos arcos teria alongado a ranhura em 3 mm.

A edição mudou apenas a ranhura. Imagem do autor.

Quão preciso foi o agente de CAD do Kimi K3.1 Pro?

O agente passou em todas as verificações ocultas nos três ensaios, dentro das tolerâncias que defini antes. Leia a tabela como um resumo:

Três ensios não são taxa de sucesso — só indicam que o resultado se manteve nesse suporte. Os furos de 6,0 mm na fase de reparo só passaram porque bateram exatamente na tolerância de ±0,5 mm — um limite mais rigoroso teria reprovado o ensaio.

A autocorreção não tinha o que corrigir

O teste que mostraria se o loop melhora um modelo é o de injeção de falhas — começando o agente a partir de um programa com erro conhecido. Eu reportaria isso em separado destes ensaios.

Custo de tokens e tempo por ensaio

Cada ensaio custou de 6,3 a 7,3 centavos por seis requisições e sete chamadas de ferramenta. Isso é só a cobrança da API — render e Docker rodaram na minha máquina.

Precifique cada requisição pelos campos usage nas tarifas publicadas de kimi-k3.1-pro. Por milhão de tokens: US$ 2,00 de input, US$ 10,00 de output, US$ 0,20 para cache hits e US$ 2,00 para gravações em cache de 5 minutos.

A primeira requisição sai mais cara porque é onde o Kimi raciocina. Output é mais da metade da conta e gravações em cache ficam entre 23% e 35%, enquanto cache hits custam quase nada. Veja como os três campos de input somam, conforme a referência de Chat Completions que linkei — você pode pular se seu tracker já separa gravações em cache:

uncached = u.prompt_tokens - cached - written   # as três partes somam prompt_tokens
cost = (uncached * 2.00 + cached * 0.20 + written * 2.00 + u.completion_tokens * 10.00) / 1e6Tecnologia

Os tokens de raciocínio já estão dentro de completion_tokens, então não os some de novo. Uma gravação em cache de 5 minutos custa o mesmo que input sem cache, então o prompt caching só compensa quando um prefixo é lido de volta. Loops de ferramenta reenviam o mesmo histórico a cada turno e, aqui, o cache reduziu a conta de input para menos de 40% da tarifa cheia.

Um ensaio leva cerca de três minutos, principalmente de espera, porque o cliente espaça as requisições em 21 segundos por causa do limite de taxa que cubro nas FAQs.

Onde a geração de CAD por IA a partir de imagens fica devendo

A principal limitação é que imagens não carregam todas as dimensões. Meu teste adiciona mais algumas:

• Renders não mostram detalhes menores que um pixel. Se uma dimensão é crítica, forneça como texto ou meça com ferramenta.
• O suporte era fácil de adivinhar. Furos fora do centro e tamanhos incomuns testariam se o Kimi lê os pixels ou os hábitos de design.
• Flags do Docker só bloqueiam o que nomeiam. Elas pararam o programa malcomportado da seção de setup, mas o código do modelo ainda pode queimar seu minuto inteiro de CPU. Nosso guia sobre como proteger agentes de IA em contêineres cobre as próximas camadas.
• Passar nessas checagens não diz nada sobre resistência. Carga, material, o raio interno que uma peça real exigiria, ajuste de parafusos e como tolerâncias se somam ficam fora deste teste.

O suporte simples é mais uma limitação do meu teste do que do Kimi.

Considerações finais

Construímos um agente que escreve código CadQuery paramétrico a partir de quatro imagens, checa o próprio sólido com ferramentas e edita um recurso sob demanda. Para este suporte, a resposta à pergunta inicial é sim. Os três ensaios passaram na primeira requisição, dentro das tolerâncias que defini, e a edição da ranhura não afetou o restante da peça.

O loop de reparo é a parte de que não posso atestar — o Kimi nunca encontrou o que reparar. A revisão deixou passar o erro de 0,5 mm porque só viu pixels, não o diâmetro verdadeiro. Eu não generalizaria o resultado para uma peça com medidas atípicas ou fotos de um objeto real.

O que levo comigo é o método: esconder a referência, congelar as regras de avaliação antes da primeira requisição e avaliar o sólido exportado — não o código. O Kimi disse que o candidato batia três vezes — e só o avaliador mostrou que estava certo duas e "quase" uma. Eu manteria esse avaliador — e meu próximo passo seria um ensaio com injeção de falhas.

Para saber mais sobre como conectar modelos às suas próprias ferramentas, nosso curso Developing AI Systems with the OpenAI API cobre function calling com o mesmo SDK usado por este agente.