Kimi K3: recursos, benchmarks, API e 5 exemplos práticos

A corrida pelos modelos abertos ganhou um novo capítulo em 16 de julho de 2026, quando a Moonshot AI lançou o Kimi K3, um modelo com 2,8 trilhões de parâmetros, janela de contexto de 1 milhão de tokens e visão nativa. É o maior modelo aberto que a Moonshot já disponibilizou, muito além do Kimi K2 em tamanho, e o primeiro que eles descrevem como chegando à classe de 3 trilhões de parâmetros.

Se você quer a história do lançamento, o mergulho na arquitetura, os gráficos de benchmark, as comparações com Claude, GPT e outros labs chineses, e a própria lista de limitações da Moonshot, nosso post no blog sobre o Kimi K3 cobre tudo isso. Este tutorial é o lado mão na massa: como acessar e como ele se comporta no uso real. Vou passar por cinco exemplos curtos, quatro via API, mostrando consumo real de tokens e custo, e dois no app web do kimi.com. Juntos, eles mostram como o K3 lida com:

• Chamar ferramentas e retornar JSON estrito
• Carregar uma definição de ferramenta sob demanda
• Reduzir o custo de longos contextos com cache automático
• Ler uma captura de tela e corrigir o layout
• Construir um dashboard interativo a partir de um único prompt

Os quatro exemplos de API rodaram em 17 de julho de 2026 com o modelo kimi-k3 e custaram cerca de 11 centavos na primeira execução (fria), ou alguns centavos depois que o cache entrou em ação.

Como acessar o Kimi K3

A forma mais rápida de testar o modelo é pelo kimi.com, onde o app web e os apps móveis rodam o Kimi K3 para tarefas gerais de agente, sem precisar configurar nada.

Para trabalhos mais pesados, como relatórios e dashboards, existe o Kimi Work, um app para desktop.

Se você vive no terminal, o Kimi Code é um agente de código que você instala via npm como @moonshot-ai/kimi-code, e você escolhe o modelo com o comando /model. Usar o K3 no Kimi Code requer uma assinatura paga, e a janela completa de 1 milhão de tokens requer um plano superior.

Este tutorial foca na API pura e no app web, mas o agente de terminal está lá caso você prefira.

O K3 não substitui seus “irmãos”. A tabela abaixo mostra como a linha atual se divide.

Em resumo, o K3 é o modelo para começar quando um trabalho mistura código, ferramentas, documentos e imagens, ou quando você realmente precisa da janela de 1 milhão de tokens. Para geração de código puro, onde velocidade importa mais que contexto, o kimi-k2.7-code ainda é a escolha mais sensata — não presuma que o modelo mais novo é sempre o melhor para sua necessidade.

Configurando a API do Kimi K3

A API é compatível com o SDK da OpenAI, então, se você já usou antes, quase nada aqui é novo. Você precisa do Python 3.9 ou superior e de uma chave de API.

Passo 1: gerar uma chave de API

Primeiro, faça login na plataforma Kimi e abra a página de API Keys no console. Crie uma chave, copie-a uma vez e guarde em um lugar seguro, porque você não a verá novamente. Você também precisa de um pequeno saldo na conta para fazer chamadas — para este tutorial inteiro, alguns dólares bastam.

Criando uma chave de API do Kimi K3. Imagem do autor.

Passo 2: instalar o SDK

Em seguida, instale o SDK da OpenAI no seu ambiente. Um único comando resolve.

python -m pip install --upgrade "openai>=1.0"

Isso traz a biblioteca cliente usada no restante dos exemplos — não há nada específico do Kimi para instalar.

Passo 3: guardar a chave e inicializar o cliente

É melhor ler a chave de uma variável de ambiente do que colá-la no código. Defina MOONSHOT_API_KEY no seu shell ou em um arquivo .env e aponte o cliente para a URL base da Moonshot.

import os
from openai import OpenAI

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

As únicas duas diferenças em relação a um setup padrão da OpenAI são o base_url e o nome do modelo, que é kimi-k3. Com isso, você já pode fazer uma chamada.

Passo 4: fazendo sua primeira chamada

Agora, a primeira requisição. Pedi para o modelo se apresentar em uma frase, o que rendeu um momento de sinceridade.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Introduce Kimi K3 in one sentence."}],
    max_completion_tokens=800,
)
print(completion.choices[0].message.content)

A resposta foi uma recusa educada a “chutar”: o modelo disse não ter informações confiáveis sobre o Kimi K3, já que foi treinado antes do próprio lançamento, e me indicou os anúncios da Moonshot. É um lembrete útil de que um modelo não sabe sobre si mesmo. Essa chamada de API custou cerca de sete décimos de centavo. Repare no limite de max_completion_tokens que usei em todas as chamadas deste tutorial para evitar que saídas muito verbosas aumentem a conta.

Primeira saída da API do Kimi K3. Imagem do autor.

Exemplo 1: streaming do raciocínio e da resposta final

O K3 sempre raciocina, e a API retorna esse raciocínio em um canal separado da resposta. Ao fazer streaming, cada chunk pode trazer reasoning_content, content final, ou ambos, para você exibir o “pensamento” e a resposta separadamente.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "A bat and a ball cost $1.10 together. The bat costs $1.00 more than the ball. How much is the ball?"}],
    max_completion_tokens=1200,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

O modelo fez streaming do passo a passo primeiro: reconheceu a pergunta do taco e da bola como o clássico Cognitive Reflection Test, apontou a resposta intuitiva (e errada) de US$ 0,10, depois resolveu a álgebra chegando a US$ 0,05 para a bola e conferiu que US$ 1,05 mais US$ 0,05 dá US$ 1,10. A separação é o que importa: em um app real você mostra o content para o usuário e guarda o reasoning_content para logs, já que exibir raciocínio bruto em produção quase nunca é o ideal. Essa chamada usou 488 tokens de saída e custou menos de um centavo.

Streaming do raciocínio e depois da resposta final. Imagem do autor.

Exemplo 2: chamada de ferramentas com saída estruturada

O Kimi K3 é o modelo da linha que suporta tool_choice="required", que força pelo menos uma chamada de ferramenta no turno. Isso é útil quando você quer que o modelo busque dados antes de responder, em vez de chutar. Aqui, dei a ele duas ferramentas mock, uma de consulta de preço e outra de estoque, forcei a chamada de ferramenta, rodei as ferramentas localmente e pedi o resultado em JSON estrito usando response_format.

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=TOOLS,
    tool_choice="required",
    max_completion_tokens=2500,
)
assistant_message = first.choices[0].message
messages.append(assistant_message)

for tool_call in assistant_message.tool_calls or []:
    args = json.loads(tool_call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": run_tool(tool_call.function.name, args)})

O modelo chamou as duas ferramentas com o código de produto correto e depois retornou um resumo limpo do pedido em JSON: cinco teclados mecânicos a US$ 89 cada, total de US$ 445, e a flag de estoque como true. Dois detalhes fazem isso funcionar na prática. Você deve anexar a mensagem completa do assistente de volta na conversa antes de adicionar os resultados das ferramentas, e deve analisar somente o content para o JSON, nunca o campo de raciocínio. O par de chamadas custou menos de um centavo somado.

Chamadas de ferramenta e saída JSON estruturada. Imagem do autor.

Exemplo 3: carregar ferramentas dinamicamente

Se você tem dezenas de ferramentas, enviar todas as definições em toda requisição desperdiça tokens e polui o prompt. O Kimi K3 permite injetar a definição de uma ferramenta no meio da conversa com uma mensagem de system que traz um campo tools e nenhum content. A ferramenta fica disponível a partir dali, o que mantém catálogos grandes fora do prefixo em cache até que a ferramenta seja realmente necessária.

messages = [
    {"role": "user", "content": "Convert 100 US dollars to euros at a rate of 0.92."},
    {"role": "system", "tools": [{
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert an amount from one currency to another",
            "parameters": {
                "type": "object",
                "properties": {"amount": {"type": "number"}, "rate": {"type": "number"}},
                "required": ["amount", "rate"],
            },
        },
    }]},
]
completion = client.chat.completions.create(model="kimi-k3", messages=messages)
print(completion.choices[0].message.tool_calls)

O K3 captou a ferramenta recém-carregada e chamou convert_currency com amount 100 e rate 0,92, exatamente como pretendido. Um ponto para não esquecer: o servidor não guarda essa definição para você, então reenvie a mensagem de system em requisições futuras se quiser manter a ferramenta disponível. Essa foi a chamada mais barata do conjunto, cerca de dois décimos de centavo.

Chamando uma ferramenta de câmbio carregada dinamicamente. Imagem do autor.

Exemplo 4: reduzindo custo de longos contextos com cache

Este exemplo mostra a janela de 1 milhão de tokens na prática. O cache de contexto é automático, sem ID de cache e sem TTL para gerenciar. Você envia um prefixo grande, mantém ele idêntico byte a byte em requisições posteriores, e a parte repetida é cobrada pela taxa de acerto de cache, não pela de falta. Para tornar a diferença visível, usei uma base de conhecimento com cerca de 33 mil tokens e fiz uma pergunta sobre ela.

knowledge = Path("knowledge_base.md").read_text(encoding="utf-8")
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": knowledge},
        {"role": "user", "content": "What is the rated payload of the Atlas robot?"},
    ],
    max_completion_tokens=600,
)

Na primeira vez, nada do prefixo estava em cache, e a requisição custou cerca de US$ 0,099 por aproximadamente 33 mil tokens de entrada. Depois que o prefixo foi visto, a mesma requisição acertou o cache em todos os 32.512 tokens do prefixo e custou cerca de US$ 0,011 — quase nove vezes menos. O motivo é a diferença de preço: entrada em cache sai a US$ 0,30 por milhão de tokens contra US$ 3,00 sem cache. Um detalhe que notei: as gravações no cache são assíncronas, então o acerto não aparece em uma chamada imediatamente subsequente. Ele entra em uma requisição posterior; rodar o script duas vezes com um minuto de intervalo mostra primeiro o miss e depois o hit.

Custo de cache miss versus cache hit. Imagem do autor.

Exemplo 5: encontrando bugs de layout em uma captura de tela

A visão é nativa no K3, e a API é uma forma limpa de usar, embora ela não aceite URL pública de imagem. Você envia a imagem como data URL em base64 e define o content da mensagem como um array de objetos — uma parte para a imagem e outra para o texto. Renderizei um pequeno dashboard com alguns bugs de layout propositais, salvei uma captura e perguntei ao K3 o que estava errado.

O dashboard com bugs de layout propositais. Imagem do autor.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("broken_dashboard.png").read_bytes()).decode()
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_data}"}},
            {"type": "text", "text": "List the layout and alignment problems you can see, and give a short CSS fix for each."},
        ],
    }],
    max_completion_tokens=3500,
)
print(completion.choices[0].message.content)

O K3 leu bem a imagem. Ele pegou o card que está mais baixo que a linha e sobrepõe o vizinho, o badge em cima de um número (ele até leu o 3.910 coberto como 5.910, o bug se denunciando), o espaço irregular antes do último card, a barra “vazando” para o card acima e o tooltip sobre as barras — e sugeriu um ajuste CSS curto para cada caso, como mover os cards para uma única grid. Mas deixou passar a legenda quase invisível por baixo contraste — visão captura mais o que salta aos olhos do que detalhes muito sutis. A chamada custou cerca de dois centavos.

Limitações do Kimi K3

Os exemplos com a API foram bem, mas há algumas arestas para você não ser pego de surpresa. Eu mesmo esbarrei na maioria delas.

• Por enquanto, só há reasoning_effort="max", então você ainda não consegue reduzir o “esforço de pensamento” para economizar.

• As configurações de amostragem são fixas. Valores como temperature, top_p e penalidades estão bloqueados; então, omita-os nas requisições em vez de tentar ajustar.

• A saída pode ficar longa e cara. Limite max_completion_tokens, como nos exemplos, e valide qualquer loop de agente.

• URLs públicas de imagem não são suportadas via API; então, planeje usar base64 ou arquivos enviados para visão.

Nada disso é um impeditivo, mas influencia como você usa o modelo. O custo da saída é o ponto a que eu daria mais atenção.

Conclusão

Nos meus testes, duas coisas chamaram atenção. A chamada de ferramentas e a saída estruturada funcionaram sem precisar repetir, e o cache importou mais do que eu esperava — reaproveitar o mesmo prefixo longo deixou barato reenviar uma requisição grande. Então, para análises em escala de repositório, chamadas repetidas de longo contexto ou engenharia multimodal, o K3 é um padrão razoável; para chat rápido e barato ou controle fino de amostragem, um modelo menor é a escolha mais simples. Os detalhes de pesos abertos e licença, que mencionei antes, devem ficar mais claros após o lançamento de 27 de julho.

Para se aprofundar nos padrões usados nestes exemplos, nosso curso Developing AI Systems with the OpenAI API cobre function calling e a conexão de modelos a ferramentas externas em Python.