A Moonshot AI lançou o Kimi K3 em 16 de julho de 2026 como seu modelo mais capaz até o momento: o primeiro modelo aberto de classe 3T, com arquitetura Mixture-of-Experts (MoE), 2,8T parâmetros e janela de contexto de 1.048.576 tokens. Para desenvolvedores, o ponto principal é a compatibilidade com a API da OpenAI: se seu projeto já usa GPT ou outro endpoint compatível, basta alterar a URL base, a chave e o modelo para kimi-k3. Neste guia, você vai configurar a chave, fazer chamadas em Python, JavaScript e cURL, implementar streaming, function calling, JSON estruturado, reasoning_effort e cache de contexto. Também verá como inspecionar requisições e eventos SSE no Apidog.
Resumo
- O ID do modelo é
kimi-k3. No OpenRouter, usemoonshotai/kimi-k3. - A API segue o formato de chat completions da OpenAI. Configure
base_url,api_keyemodel="kimi-k3". - Confirme a URL base no console em platform.kimi.ai. Historicamente, o Kimi usou
https://api.moonshot.ai/v1. - A janela de contexto é de 1M tokens.
- O preço informado é de US$ 0,30 por milhão de tokens de entrada com cache-hit, US$ 3,00 por milhão de tokens de entrada com cache-miss e US$ 15,00 por milhão de tokens de saída.
- Streaming, chamadas de ferramentas, modo JSON, saída estruturada e
reasoning_effortfuncionam pelo contrato de chat completions. - Para cargas de trabalho de código rotineiras e alto volume, a linha K2.7 pode ter melhor custo-benefício.
- Use o Apidog para enviar a requisição HTTP bruta, observar eventos SSE, testar ferramentas e comparar
kimi-k3comkimi-k2-7-code.
Qual modelo Kimi você deve usar?
Escolha o modelo antes de implementar a integração.
O Kimi K3 é o modelo de ponta da família, voltado para codificação complexa, agentes de longa duração e tarefas com contexto extenso. Ele usa uma arquitetura MoE grande e tem custo de saída mais alto. No próprio post de lançamento, a Moonshot informa que o K3 fica atrás de Claude Fable 5 e GPT-5.6 Sol em suas comparações internas.
Use kimi-k3 quando precisar de:
- raciocínio mais profundo;
- janela de contexto de 1M tokens;
- orquestração de ferramentas para agentes;
- análise de documentos ou bases de código grandes.
Para assistentes de código de alto volume, geração de testes de CI ou edições mecânicas, a linha K2.7 Code pode ser mais econômica. Consulte o guia da API Kimi K2.7 Code, a explicação sobre o que é Kimi K2.7 Code e a comparação Kimi K3 vs Kimi K2.7 Code.
Para uma visão geral do K3, leia também o que é Kimi K3.
Obtenha uma chave de API na plataforma Kimi
Acesse platform.kimi.ai e faça login. No console, você cria chaves, monitora consumo e confirma a URL base da sua conta.
- Abra a seção de chaves de API.
- Crie uma nova chave.
- Copie o valor imediatamente e armazene-o em um gerenciador de segredos.
- Confirme que sua conta tem crédito ou um plano de cobrança ativo.
- Copie a URL base exibida no console.
O Kimi historicamente usou https://api.moonshot.ai/v1, mas o console é a fonte da verdade para sua conta.
Exporte a chave como variável de ambiente:
export KIMI_API_KEY="sk-your-key-here"
export KIMI_BASE_URL="https://api.moonshot.ai/v1"
Não coloque a chave no código-fonte, em arquivos versionados ou em capturas de tela. Ao testar no Apidog, crie uma variável de ambiente com o mesmo segredo.
Para entender o impacto financeiro de cache-hit e cache-miss, consulte o guia de preços do Kimi K3.
Início rápido: primeira chamada ao kimi-k3
A API usa o contrato de chat completions da OpenAI. Na prática, você reutiliza o SDK da OpenAI e altera:
-
api_key; -
base_url; -
model.
Python
Instale o SDK:
pip install openai
Faça uma chamada:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["KIMI_API_KEY"],
# Confirme a URL base no console da Kimi.
base_url=os.environ["KIMI_BASE_URL"],
)
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "system",
"content": "Você é um assistente de codificação preciso.",
},
{
"role": "user",
"content": "Explique o que faz um limitador de taxa token bucket em um parágrafo.",
},
],
)
print(response.choices[0].message.content)
JavaScript / TypeScript
Instale o SDK:
npm install openai
Faça uma chamada:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.KIMI_API_KEY,
// Confirme a URL base no console da Kimi.
baseURL: process.env.KIMI_BASE_URL,
});
const response = await client.chat.completions.create({
model: "kimi-k3",
messages: [
{
role: "system",
content: "Você é um assistente de codificação preciso.",
},
{
role: "user",
content: "Explique o que faz um limitador de taxa token bucket em um parágrafo.",
},
],
});
console.log(response.choices[0].message.content);
cURL
curl "$KIMI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3",
"messages": [
{
"role": "user",
"content": "Explique o que faz um limitador de taxa token bucket em um parágrafo."
}
]
}'
Diagnóstico rápido de erros
| Status | Causa provável | Ação |
|---|---|---|
401 Unauthorized |
Chave ausente, inválida ou expirada | Verifique KIMI_API_KEY
|
404 Not Found |
URL base ou caminho incorreto | Confirme KIMI_BASE_URL no console |
| Falha por saldo | Conta sem crédito ou cobrança não configurada | Verifique o plano no console |
| Modelo não responde como esperado | Campo ou payload incompatível | Inspecione a requisição bruta no Apidog |
A documentação do SDK Python da OpenAI detalha as opções do cliente. Como a API segue o mesmo formato de comunicação, essas configurações também são relevantes para a integração com Kimi.
Respostas em streaming
Para chats, interfaces de agente e respostas longas, habilite streaming. Assim, você recebe tokens conforme eles são gerados, em vez de esperar a resposta completa.
Streaming em Python
stream = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": "Escreva um poema de 6 linhas sobre testes instáveis.",
}
],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
Streaming em JavaScript
const stream = await client.chat.completions.create({
model: "kimi-k3",
messages: [
{
role: "user",
content: "Escreva um poema de 6 linhas sobre testes instáveis.",
},
],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
Nos bastidores, a resposta é enviada como Server-Sent Events (SSE). Os frames normalmente chegam como linhas data: contendo pequenos objetos JSON, e o stream termina com:
data: [DONE]
O SDK abstrai esses frames, mas observar o SSE bruto é útil quando uma conexão é interrompida ou quando seu parser não trata corretamente os chunks parciais.
Chamadas de ferramentas com function calling
O Kimi K3 suporta chamadas de ferramentas, restrição de escolha de ferramenta e carregamento dinâmico de ferramentas.
O fluxo é:
- Descreva a ferramenta com JSON Schema.
- Envie a lista em
tools. - Receba o pedido de execução em
tool_calls. - Execute a função no seu backend.
- Envie o resultado em uma mensagem com
role: "tool". - Faça uma nova chamada para obter a resposta final.
Defina uma ferramenta
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Obtém o clima atual para uma cidade.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Nome da cidade, por exemplo: Singapura",
},
},
"required": ["city"],
},
},
}
]
messages = [
{
"role": "user",
"content": "Qual é o clima em Singapura agora?",
}
]
first = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
tool_choice="auto",
)
tool_call = first.choices[0].message.tool_calls[0]
print(tool_call.function.name) # get_weather
print(tool_call.function.arguments) # {"city": "Singapura"}
O modelo não executa sua função. Ele apenas retorna o nome da ferramenta e os argumentos. Seu código continua responsável por autenticação, autorização, acesso a APIs externas e tratamento de erros.
Retorne o resultado da ferramenta
import json
# Mantém a mensagem do assistente que solicitou a ferramenta.
messages.append(first.choices[0].message)
# Envia o resultado real produzido pelo seu backend.
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps({
"city": "Singapura",
"temp_c": 31,
"sky": "úmido",
}),
})
final = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
)
print(final.choices[0].message.content)
Controle a escolha da ferramenta
Force o uso de alguma ferramenta:
tool_choice = "required"
Force uma função específica:
tool_choice = {
"type": "function",
"function": {
"name": "get_weather",
},
}
Use uma função fixada quando seu fluxo já sabe qual ação deve ocorrer. Use auto quando o modelo precisa decidir se a ferramenta é necessária.
Ao criar agentes com múltiplas interações, preserve o histórico completo das mensagens, incluindo as interações internas do assistente. O K3 foi treinado com histórico de pensamento preservado; descartar etapas anteriores pode deixar a geração instável.
Modo JSON e saída estruturada
Para integrar a resposta a bancos de dados, automações ou pipelines, evite analisar texto livre. Solicite JSON diretamente.
Modo json_object
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "system",
"content": "Retorne apenas JSON válido. Sem texto adicional e sem markdown.",
},
{
"role": "user",
"content": "Extraia nome e função de: 'Ada Lovelace, matemática'.",
},
],
response_format={"type": "json_object"},
)
print(response.choices[0].message.content)
# {"name": "Ada Lovelace", "role": "matemática"}
Mesmo com json_object, valide o resultado antes de gravá-lo ou usá-lo em produção:
import json
content = response.choices[0].message.content
data = json.loads(content)
assert "name" in data
assert "role" in data
Saída com JSON Schema
Se a versão do SDK e sua conta suportarem json_schema, descreva o formato esperado:
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": "Extraia nome e função de: 'Ada Lovelace, matemática'.",
}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "person",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"role": {"type": "string"},
},
"required": ["name", "role"],
},
},
},
)
Confirme o suporte a json_schema no console antes de depender dele em produção. Quando houver dúvida, use json_object e valide o payload no seu backend.
O Kimi também expõe modo parcial e pesquisa na internet, úteis para preencher respostas progressivamente ou fundamentar respostas em dados recentes.
Esforço de raciocínio configurável
O parâmetro reasoning_effort controla o esforço de raciocínio antes da resposta.
No momento, o nível disponível é max, que também é o padrão. Segundo a Moonshot, níveis adicionais estão planejados.
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": "Planeje uma migração de REST para GraphQL para uma API de 40 endpoints.",
}
],
reasoning_effort="max",
)
Mais raciocínio pode aumentar a qualidade em planejamento e análise complexa, mas também aumenta latência e consumo de tokens de saída.
Se sua versão do SDK ainda não reconhecer esse campo, envie-o com extra_body:
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": "Planeje uma migração de REST para GraphQL.",
}
],
extra_body={
"reasoning_effort": "max",
},
)
Esse padrão também é útil para outros campos específicos do provedor que ainda não foram incorporados ao SDK base.
Testando e depurando kimi-k3 no Apidog
O SDK simplifica a integração, mas esconde detalhes importantes do HTTP. Quando um stream falha, uma ferramenta retorna argumentos inesperados ou uma requisição recebe erro, é útil visualizar a requisição e a resposta sem abstrações.
O Apidog permite enviar a mesma chamada usada pelo seu código, armazenar a chave como variável de ambiente e observar eventos SSE quadro a quadro. Para o fluxo geral, veja o passo a passo para testar APIs sem Postman.
Configure a requisição
- Crie uma nova requisição HTTP no Apidog.
- Selecione o método
POST. - Defina a URL:
{{KIMI_BASE_URL}}/chat/completions
-
Crie as variáveis de ambiente:
KIMI_BASE_URLKIMI_API_KEY
Adicione os cabeçalhos:
Authorization: Bearer {{KIMI_API_KEY}}
Content-Type: application/json
- Cole o payload:
{
"model": "kimi-k3",
"messages": [
{
"role": "user",
"content": "Explique o que faz um limitador de taxa token bucket em um parágrafo."
}
]
}
Inspecione streaming
Adicione "stream": true ao corpo:
{
"model": "kimi-k3",
"stream": true,
"messages": [
{
"role": "user",
"content": "Escreva um poema de 6 linhas sobre testes instáveis."
}
]
}
No Apidog, observe os frames data: recebidos. Isso ajuda a identificar:
- conexão encerrada antes de
[DONE]; - chunks sem conteúdo;
- parser que não lida com JSON parcial;
- campos inesperados em
delta.
Depure chamadas de ferramentas
Envie uma requisição com tools e inspecione o array tool_calls na resposta.
Verifique especialmente:
- se a função esperada foi selecionada;
- se
argumentscontém JSON válido; - se os campos obrigatórios foram preenchidos;
- se a descrição da ferramenta está ambígua;
- se o backend está retornando o resultado com o mesmo
tool_call_id.
Compare K3 e K2.7
Duplique a requisição e altere apenas o modelo:
{
"model": "kimi-k2-7-code"
}
Compare os dois endpoints usando o mesmo prompt e os mesmos parâmetros:
- latência;
- qualidade da resposta;
- quantidade de tokens;
- custo;
- comportamento em tool calling;
- aderência ao formato JSON.
Esse teste A/B é a forma mais direta de decidir se o custo adicional do K3 é justificado para seu caso de uso.
Como o Apidog importa requisições compatíveis com OpenAI, você também pode importar o comando cURL diretamente e salvá-lo como um caso de teste reutilizável. Para fluxos com MCP, consulte o guia de depuração visual com o cliente MCP do Apidog.
Baixe o Apidog para reproduzir esse fluxo com sua própria chave.
Casos de uso práticos
Agentes de codificação em escala de repositório
Use o contexto de 1M tokens e as ferramentas para permitir que o agente:
- leia arquivos;
- execute testes;
- consulte logs;
- proponha alterações;
- itere com base nos resultados.
Para maximizar cache-hit, mantenha o resumo da base de código e as instruções do sistema como prefixos estáveis no prompt.
Processamento de documentos longos
Envie especificações, contratos ou corpus de pesquisa e extraia dados com json_schema.
Estratégia recomendada:
- coloque o documento compartilhado no início do prompt;
- mantenha esse conteúdo idêntico entre chamadas;
- altere apenas a consulta final;
- valide o JSON retornado antes de persistir dados.
Essa estrutura aumenta a chance de reutilização de cache.
Planejamento de migração e refatoração
Use reasoning_effort="max" na fase de planejamento:
- inventário de endpoints;
- mapeamento de dependências;
- análise de riscos;
- estratégia de rollback;
- plano de testes.
Depois, direcione tarefas mecânicas, como alterações repetitivas de código, para um modelo mais barato quando fizer sentido.
Respostas fundamentadas em dados recentes
Com pesquisa na internet e chamadas de ferramentas, o K3 pode consultar fontes externas para respostas que não dependam exclusivamente do conhecimento de treinamento. Esse padrão é adequado para assistentes que precisam acessar dados atualizados.
Conclusão
Para chamar o Kimi K3, configure três itens em um cliente compatível com OpenAI:
base_url = URL exibida no console Kimi
api_key = sua chave de API
model = "kimi-k3"
A partir daí, você pode usar streaming, function calling, modo JSON, JSON Schema e reasoning_effort com o formato de chat completions que já conhece.
Os dois pontos mais importantes para implementação são:
- Cache de contexto: manter um prefixo estável pode reduzir a entrada de US$ 3,00 para US$ 0,30 por milhão de tokens na porção com cache-hit.
- Escolha de modelo: use K3 para raciocínio, contexto longo e agentes; use K2.7 para trabalho rotineiro de alto volume quando o custo for prioritário.
Implemente a chamada no SDK, valide o comportamento HTTP no Apidog e só então conecte o fluxo ao seu aplicativo.
FAQ
Qual é o ID do modelo da API para Kimi K3?
Na plataforma Kimi, o ID é:
kimi-k3
No OpenRouter, o slug é:
moonshotai/kimi-k3
Veja a listagem em openrouter.ai/moonshotai/kimi-k3.
Qual URL base devo usar?
Confirme a URL no console em platform.kimi.ai. Historicamente, o Kimi usou:
https://api.moonshot.ai/v1
Evite fixar essa URL diretamente no código. Prefira uma variável de ambiente como KIMI_BASE_URL.
O Kimi K3 é compatível com o SDK da OpenAI?
Sim. A API segue o formato de chat completions da OpenAI. Os SDKs Python e JavaScript funcionam após alterar base_url, api_key e model.
Para campos específicos do provedor que ainda não existem no SDK, use extra_body.
Quanto custa a API do Kimi K3?
O preço informado é:
- US$ 0,30 por milhão de tokens de entrada com cache-hit;
- US$ 3,00 por milhão de tokens de entrada com cache-miss;
- US$ 15,00 por milhão de tokens de saída.
Consulte o guia de preços do Kimi K3 para mais detalhes.
O que o cache de contexto faz?
Quando o início de uma requisição corresponde ao de uma chamada anterior, o endpoint pode reutilizar o estado computado em vez de recalcular essa parte.
Para aumentar cache-hit:
- mantenha o prompt de sistema estável;
- mantenha documentos ou contexto compartilhado no início;
- adicione perguntas variáveis apenas no final;
- evite alterar desnecessariamente o prefixo do prompt.
Posso controlar o quanto o modelo pensa?
Sim. Use:
reasoning_effort="max"
Atualmente, max é o nível disponível e também o padrão. Mais esforço pode aumentar a latência e o consumo de tokens de saída.
Devo usar Kimi K3 ou Kimi K2.7 Code?
Use kimi-k3 para:
- raciocínio mais profundo;
- contexto de 1M tokens;
- orquestração de ferramentas;
- tarefas complexas de agentes.
Use K2.7 quando precisar de maior eficiência de custo em tarefas de codificação rotineiras e alto volume. Consulte a comparação Kimi K3 vs Kimi K2.7 Code e o guia da API Kimi K2.7 Code.
Como depuro uma resposta quebrada de streaming ou uma chamada de ferramenta?
Envie a requisição HTTP bruta no Apidog:
- para streaming, use
"stream": truee observe os frames SSE; - para ferramentas, inspecione
tool_calls; - para JSON, valide o corpo retornado;
- para autenticação, mantenha a chave em uma variável de ambiente;
- para comparação de modelos, duplique a requisição e altere apenas
model.
Top comments (0)