Guia de integração da API e uso de agentes do Kimi K3.1 Pro
Kimi K3.1 Pro é um modelo da série K3.1 da Moonshot AI, voltado para programação, criação 3D, pesquisa financeira e tarefas longas com agentes. O ID oficial do modelo na API é kimi-k3.1-pro, e a URL base do OpenAI SDK é https://api.moonshot.cn/v1. O modo de pensamento fica sempre ativado; a intensidade de raciocínio pode ser definida como low, high ou max, sendo max o padrão. Início rápido oficial
Este guia aborda integração, raciocínio, visão e ciclos de ferramentas com base na documentação oficial. Resultados de benchmark publicados pelo fornecedor são avaliações do próprio fornecedor, não testes da Guishu Intelligence.
Informações principais
| Item | Informação verificada |
|---|---|
| ID oficial do modelo | kimi-k3.1-pro |
| URL base oficial da API | https://api.moonshot.cn/v1 |
| Intensidade de raciocínio | low, high, max; padrão max |
| Modo de pensamento | Sempre ativado |
| Contexto | A documentação oficial informa suporte a 1 milhão de tokens |
| Variante de alta velocidade | kimi-k3.1-pro-highspeed; modelo independente; consulte o catálogo da plataforma para disponibilidade e preço |
| Data de verificação da documentação | 2026-10-24 |
As informações sobre capacidades e variantes seguem a documentação oficial do Kimi K3.1 Pro. Versões, elegibilidade de acesso e preços podem mudar; consulte os preços dos modelos para verificar o que está disponível na plataforma.
Para que serve esta atualização?
O destaque do K3.1 Pro está em tarefas com várias etapas: entender requisitos, gerar um artefato, conferir o resultado e revisá-lo com base no retorno recebido. Um contexto de 1 milhão de tokens permite incluir mais materiais, mas o sucesso de tarefas longas também depende das ferramentas, do ambiente e dos critérios de aceitação. Os exemplos a seguir tratam de programação, criação 3D e pesquisa financeira; vêm de relatos de terceiros e demonstrações do fornecedor, não de execuções nossas.
Câmera 3D: conferir se a estrutura muda com os parâmetros
Em seu artigo “Modelos chineses deram mais um grande passo: teste do Kimi K3.1 Pro”, Liu Xiaopai pediu que vários modelos criassem câmeras interativas. Segundo o autor, o K3.1 Pro gerou 34 peças selecionáveis e 9 lâminas de diafragma, e 35 leituras ópticas atenderam aos critérios de verificação dele. Na segunda rodada, ao mudar a lente de 50 mm para 85 mm, o modelo também alterou a geometria em vez de apenas trocar o rótulo.
O mesmo caso teve falhas: as unidades de exportação não foram tratadas conforme solicitado, e havia um problema de espaço entre a estrutura do corpo e o diafragma. Em tarefas de design, é mais útil verificar dimensões, interação, arquivos exportados e possibilidade de edição posterior em conjunto, em vez de avaliar apenas uma imagem renderizada. O autor usou diferentes ambientes de ferramentas de programação, portanto suas impressões não constituem uma comparação com variáveis controladas.
Mapa de jogo: criar uma ferramenta e depois deixar o agente usá-la
O mesmo autor também criou um editor de mapas de Terraria para navegador. Os blocos precisavam respeitar as regras do jogo, e o mapa exportado deveria poder ser usado novamente no jogo. Depois, ele pediu ao K3.1 Pro que montasse um cenário com o editor gerado. Essa tarefa combina compreensão de formatos de arquivo, desenvolvimento de interface e operação de ferramentas, aproximando-se mais de um fluxo real de trabalho do que a geração de um trecho de código demonstrativo. O autor observou qualidades visuais diferentes no Kimi e nos modelos comparados; é uma percepção pessoal, não uma conclusão estética universal.
Pesquisa financeira: conferir fórmulas e referências, não apenas conclusões
Os materiais de Zenan, Zhang Qian e Panda, da equipe editorial do jiqizhixin.com, reúnem exemplos de modelagem financeira, relatórios de pesquisa e engenharia 3D. A documentação oficial também mostra um modelo financeiro com premissas operacionais ajustáveis e um relatório de pesquisa com fontes. O ponto útil desses exemplos é o critério de validação: as fórmulas são recalculadas quando as premissas mudam? É possível rastrear os números importantes até os arquivos originais? Cada referência do relatório pode ser aberta? Uma demonstração do fornecedor não garante precisão em qualquer tarefa financeira. Descrição oficial de capacidades e exemplos
Na data de verificação deste artigo, o fornecedor dizia que planejava abrir os pesos completos até 4 de novembro. Isso é um plano, não uma publicação já realizada; os recursos 3D do aplicativo oficial também não significam que a API inclua uma ferramenta de modelagem.
Chamada básica da API
O exemplo oficial usa Python 3.9+ e OpenAI SDK. Armazene a chave de API em uma variável de ambiente; não a inclua no código-fonte nem a envie ao repositório.
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": "Explique em três pontos como criar um processo confiável de revisão de código."}],
reasoning_effort="high",
)
print(result.choices[0].message.content)
Para chamar diretamente a Moonshot, use uma chave emitida pela Moonshot e a URL base oficial acima. Se usar um serviço de terceiros compatível com a API, substitua a URL base, a chave e o ID do modelo pelos dados fornecidos por esse serviço; não compartilhe credenciais oficiais com terceiros. Os modelos atualmente disponíveis e a forma de cobrança da Guishu Intelligence estão na página de preços.
Como escolher a intensidade de raciocínio
O K3.1 Pro permanece sempre no modo de pensamento. reasoning_effort controla a intensidade do raciocínio, não liga nem desliga esse modo. A documentação oficial oferece low, high e max, com max como padrão. Explicação oficial da intensidade de raciocínio
- Para respostas curtas ou transformações com requisitos bem definidos, comece testando
low. - Para alterações de código em várias etapas, análise e planejamento, experimente
highprimeiro. - Para tarefas complexas que exigem raciocínio mais profundo, compare a qualidade, a latência e o custo real de
max.
Estas são recomendações de fluxo de trabalho, não garantias de desempenho. Em produção, avalie precisão, latência e custo nas suas próprias tarefas.
Conversas em várias etapas: mantenha a mensagem assistant completa
Para conversas com várias etapas e respostas de ferramentas, a documentação oficial pede que a mensagem assistant completa retornada pela API seja incluída na solicitação seguinte, em vez de manter apenas o texto content. Campos estruturados, como chamadas de ferramentas, podem ser necessários nas etapas posteriores. Documentação oficial sobre conversas em várias etapas
messages = [{"role": "user", "content": "Liste primeiro o plano de migração e depois explique os riscos."}]
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": "Transforme a seção de riscos em uma lista de verificação."})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)
Se o aplicativo precisar manter uma sessão entre solicitações, salve os campos de mensagem exigidos pelo protocolo e confira na documentação oficial como o SDK serializa os objetos de mensagem.
Chamadas de ferramentas e ciclo do agente
O aplicativo define e executa as ferramentas: o modelo gera uma chamada, o aplicativo valida os parâmetros, chama a função real e devolve o resultado ao modelo. Não execute a saída do modelo diretamente como se fosse um comando confiável.
import json
tools = [{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Consultar o status de um pedido",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Consulte o status do 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) # Mantenha a mensagem assistant completa
for call in assistant.tool_calls or []:
args = json.loads(call.function.arguments)
# Em um aplicativo real, valide primeiro os parâmetros e as permissões do usuário e só então chame a função de negócio 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)
O guia oficial de chamadas de ferramentas também exige devolver cada resultado com o tool_call_id correspondente e manter a mensagem assistant completa na etapa seguinte. Cabe ao aplicativo implementar autenticação, validação de parâmetros, limites de tempo, idempotência e auditoria.
Entrada visual: use uma matriz de objetos
A documentação oficial especifica que content de uma mensagem visual é uma matriz de objetos, não uma string serializada. O exemplo envia a imagem como Data URL Base64; o fluxo de arquivos compatível também pode usar referências ms://. Não presuma que uma URL pública comum de imagem possa ser lida diretamente. Instruções oficiais 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": "Descreva os componentes do sistema e as conexões entre eles no diagrama."},
],
}],
)
print(response.choices[0].message.content)
Antes da integração, confira os limites de formato e tamanho de imagem e as restrições da interface de arquivos. Antes de enviar imagens sensíveis a um modelo externo, verifique também as regras de tratamento de dados da sua organização.
Como interpretar benchmarks oficiais e experiências de terceiros
A Moonshot informa que o K3.1 Pro obteve 65,7% no Terminal-Bench 4.0 e apresenta uma comparação com GPT-6 Astra e Claude Opus 5.5. Esses números são resultados divulgados pelo fornecedor e devem ser entendidos considerando o conjunto de tarefas, a configuração do teste e a data de publicação. Não é possível generalizá-los como taxa de sucesso em todas as tarefas de programação. Apresentação oficial do modelo e benchmarks
O autor independente Liu Xiaopai compartilhou experiências, incluindo uma câmera 3D interativa, e sua avaliação pessoal dos modelos comparados. Isso não é um teste da Guishu Intelligence nem uma comparação uniforme e reproduzível. Para avaliar um modelo, use seus próprios repositórios, restrições de design e exemplos de falha; registre prompts, ferramentas, tentativas, latência e custos.
Lista de verificação da integração
- Confirme se a chamada será direta ao fornecedor oficial ou por um serviço compatível e use o ID do modelo, a URL base e a chave correspondentes.
- Comece com uma intensidade de raciocínio menor e compare gradualmente qualidade, latência e cobrança em tarefas representativas.
- Em cenários de várias etapas e de agente, salve a mensagem assistant completa e associe corretamente os resultados das ferramentas.
- Monte mensagens visuais como matrizes de objetos; para imagens locais, use a codificação ou o fluxo de arquivos oficialmente compatível.
- Defina limites de permissão, validação de parâmetros, tempos limite e tratamento de falhas para a execução das ferramentas.
- Antes da implantação, confira o catálogo atual de modelos, as regiões disponíveis e os preços; não reutilize uma configuração antiga sem verificar.
Perguntas frequentes
Qual é o ID do modelo API do Kimi K3.1 Pro?
A documentação oficial informa kimi-k3.1-pro. A variante de alta velocidade é kimi-k3.1-pro-highspeed; não confunda os dois na configuração do modelo.
Qual é a intensidade de raciocínio padrão?
A documentação oficial lista low, high e max, com max como padrão. O modo de pensamento do modelo permanece sempre ativado.
Posso enviar diretamente uma URL de imagem?
A documentação oficial não oferece suporte a URLs públicas de imagem. Use uma matriz de objetos visuais com Data URL Base64 ou, pelo fluxo de arquivos, uma referência ms://.
Por que o agente precisa devolver a mensagem assistant completa?
Ela pode conter campos estruturados, como chamadas de ferramentas. Salvar apenas o texto perde informações necessárias para a interação seguinte; o resultado da ferramenta também precisa usar o tool_call_id correspondente.
A Guishu Intelligence oferece o Kimi K3.1 Pro?
Consulte a página de preços para ver os modelos, roteamento e preços disponíveis atualmente. O acesso direto do fornecedor não significa que este modelo ou sua variante de alta velocidade seja oferecido aqui.
Para continuar
Data de verificação das informações oficiais: 2026-10-24. Capacidades do modelo, parâmetros da API e condições de acesso podem mudar; consulte a documentação da API Kimi da Moonshot.