Blog

Como usar a API Kimi K3?

Chame a API Kimi K3 com o SDK da OpenAI: guias de início rápido para Python, JavaScript e cURL, além de streaming, chamadas de ferramentas, modo JSON, esforço de raciocínio e cache.

Ashley Innocent

Ashley Innocent

17 julho 2026

Como usar a API Kimi K3?

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

A Moonshot AI lançou o Kimi K3 em 16 de julho de 2026, e o chamou de seu modelo mais capaz até o momento: o primeiro modelo de classe 3T aberto do mundo, com um design Mixture-of-Experts de 2,8T parâmetros e uma janela de contexto de 1.048.576 tokens. A parte interessante para os desenvolvedores não é o tamanho, é a API. O Kimi K3 fala o dialeto do SDK da OpenAI, então se você já usa o GPT ou qualquer endpoint compatível com OpenAI, você pode apontar o mesmo cliente para kimi-k3 e começar a transmitir respostas em poucos minutos. Este guia aborda como obter uma chave, o início rápido em Python, JavaScript e cURL, streaming, chamadas de ferramentas, modo JSON, o parâmetro configurável de esforço de raciocínio e o cache de contexto que torna a entrada com cache-hit aproximadamente dez vezes mais barata do que com cache-miss. Em seguida, você testará e depurará essas chamadas no Apidog para que você possa ver a requisição bruta e os eventos enviados pelo servidor em vez de tentar adivinhar.

Resumo

Qual modelo Kimi você deve usar?

Antes de escrever qualquer código, escolha o alvo certo. O Kimi K3 é o modelo de ponta da família: um grande MoE (Mixture-of-Experts) voltado para codificação complexa, trabalho de agente de longo prazo e tarefas de conhecimento em contextos longos. Ele tem o maior custo por token de saída da linha, e o próprio post de lançamento da Moonshot é franco ao dizer que o K3 fica atrás do Claude Fable 5 e do GPT-5.6 Sol em suas comparações internas. É forte, não é um vencedor claro da fronteira, e tem um preço de acordo.

Se sua carga de trabalho for um assistente de codificação de alto volume, um escritor de testes de CI, ou qualquer coisa em que você esteja pagando por chamada em escala, a linha K2.7 Code mais antiga costuma ser a melhor opção em termos de custo. Comece com o guia da API Kimi K2.7 Code e a visão geral o que é Kimi K2.7 Code para ver se esse nível atende ao seu caso. Para uma comparação lado a lado de capacidade e preço, a comparação Kimi K3 vs Kimi K2.7 Code descreve onde cada um se destaca. Opte por kimi-k3 quando precisar de profundidade de raciocínio extra, do contexto completo de 1M, ou da orquestração de ferramentas de agente; mude para K2.7 quando a tarefa for rotineira e o volume for alto. Se você quiser uma descrição completa das capacidades primeiro, o explicativo o que é Kimi K3 aborda a arquitetura e onde o modelo se encaixa.

Obtenha uma chave de API na plataforma Kimi

Acesse platform.kimi.ai e faça login. O novo console é onde você cria chaves, monitora o uso e confirma a URL base para sua conta.

  1. Abra a seção de chaves de API do console e crie uma nova chave.
  2. Copie-a uma vez e guarde-a em um local seguro. Você não verá o valor completo novamente.
  3. Adicione crédito ou confirme seu plano de cobrança para que as chamadas para kimi-k3 não sejam rejeitadas por saldo insuficiente.
  4. Anote a URL base mostrada no console. O Kimi historicamente usou https://api.moonshot.ai/v1; o console é a fonte da verdade para sua conta.

Exporte a chave como uma variável de ambiente para que ela nunca chegue ao seu código-fonte:

export KIMI_API_KEY="sk-your-key-here"

Esse único hábito mantém segredos fora do histórico do git e de capturas de tela. Mais tarde, quando você testar no Apidog, armazenará o mesmo valor como uma variável de ambiente lá também, para que a chave viva em exatamente dois lugares que você controla.

Para uma análise completa da matemática de cache-hit versus cache-miss e como ela se traduz em contas mensais reais, consulte o guia de preços do Kimi K3.

Início Rápido: sua primeira chamada ao kimi-k3

A API do Kimi segue o contrato de chat-completions da OpenAI, então os SDKs oficiais da OpenAI funcionam com duas alterações: o base_url e o model. Instale o SDK de sua preferência e, em seguida, execute um dos trechos abaixo.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # O Kimi é compatível com o SDK da OpenAI. Confirme a URL base exata no
    # console em platform.kimi.ai; o Kimi historicamente usou o valor abaixo.
    base_url="https://api.moonshot.ai/v1",
)

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 de token bucket em um parágrafo."},
    ],
)

print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Confirme a URL base no console platform.kimi.ai.
  baseURL: "https://api.moonshot.ai/v1",
});

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 de 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 de token bucket em um parágrafo."}
    ]
  }'

Defina KIMI_BASE_URL para o que o console mostrar (por exemplo, https://api.moonshot.ai/v1). Se alguma dessas chamadas retornar um 401, a chave está errada ou não definida. Um 404 no caminho geralmente significa que a URL base está incorreta, não que o modelo esteja faltando. A documentação do SDK Python da OpenAI cobre as opções do cliente com mais detalhes, e todas as opções lá se aplicam aqui porque o formato de comunicação é o mesmo.

Respostas em streaming

Para interfaces de usuário de chat e longas interações de agente, você deseja que os tokens cheguem assim que disponíveis, em vez de esperar pela conclusão completa. Defina stream=True e itere sobre os deltas.

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)

Nos bastidores, este é um stream de eventos enviados pelo servidor (SSE): cada linha é um frame data: contendo um pequeno pedaço de JSON, e o stream termina com data: [DONE]. O SDK esconde essa estrutura de você, o que é conveniente até que algo quebre no meio do stream e você precise ver os frames brutos. Esse é um dos pontos onde a seção Apidog abaixo se mostra valiosa.

A mesma flag funciona 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 ?? "");
}

Chamadas de ferramentas (function calling)

O Kimi K3 suporta chamadas de ferramentas, restrições de escolha de ferramenta e carregamento dinâmico de ferramentas, para que você possa conectá-lo a agentes que leem arquivos, acessam APIs ou executam comandos de terminal. Você descreve suas funções com JSON Schema, o modelo decide quando chamar uma, e você retorna o resultado em uma mensagem tool.

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, ex: 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)       # obter_clima
print(tool_call.function.arguments)  # {"city": "Singapura"}

O modelo não executa sua função; ele te entrega um nome e argumentos JSON. Você executa o trabalho real, então alimenta o resultado de volta para que o modelo possa escrever uma resposta final:

import json

# Anexa a resposta do assistente que pediu a ferramenta, e então o resultado da ferramenta.
messages.append(first.choices[0].message)
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)

Defina tool_choice="required" para forçar uma chamada de ferramenta, ou passe um objeto específico {"type": "function", "function": {"name": "get_weather"}} para fixar uma função. Essas restrições mantêm um agente nos trilhos quando você já sabe qual ferramenta deve ser acionada.

Uma pegadinha específica do K3 que vale a pena saber logo: o modelo foi treinado no modo de histórico de pensamento preservado. Se o seu mecanismo de agente descartar o raciocínio anterior do modelo entre as interações, a qualidade da geração pode ficar instável. Ao construir um loop de agente multi-turno, passe todo o histórico de mensagens de volta em vez de cortar as interações internas do assistente.

Modo JSON e saída estruturada

Quando você precisa de uma saída legível por máquina, peça JSON diretamente em vez de analisar texto. Defina response_format para json_object e instrua o modelo a retornar JSON.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Retorne apenas JSON válido. Sem texto, 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"}

Para garantias mais estritas, o Kimi suporta saída estruturada contra um esquema. Se a sua versão do SDK aceitar, passe um formato de resposta json_schema para que o modelo se ajuste à sua forma:

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 para sua conta no console antes de implementá-lo; em caso de dúvida, json_object mais uma etapa de validação do seu lado é o fallback seguro. O Kimi também expõe um modo parcial e pesquisa na internet, o que ajuda quando você deseja preencher uma resposta do assistente ou fundamentar respostas em dados recentes.

Esforço de raciocínio configurável

O Kimi K3 expõe um parâmetro reasoning_effort que controla o quanto o modelo "pensa" antes de responder. Atualmente, o nível disponível é max, que também é o padrão; a Moonshot afirmou que níveis mais baixos e mais altos estão planejados. Um pensamento mais profundo custa mais tokens de saída e adiciona latência, então é uma alavanca que você ajusta por tarefa.

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",
)

Se a sua versão do SDK da OpenAI rejeitar o campo como desconhecido, passe-o através do mecanismo de escape (escape hatch) em vez disso:

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"},
)

O padrão extra_body é como você envia qualquer campo específico do provedor que o SDK base ainda não modelou, o que é comum quando um endpoint compatível se move mais rápido do que a biblioteca cliente.

Testando e depurando kimi-k3 no Apidog

O código do SDK esconde o formato de comunicação, o que é bom até que uma chamada de ferramenta retorne o formato errado ou um stream seja interrompido e você não consiga dizer se a falha é sua ou do endpoint. É aqui que um cliente de API que fala HTTP puro compensa. O Apidog permite que você envie a requisição exata do kimi-k3, observe o stream SSE quadro a quadro e mantenha sua chave fora do corpo da requisição. Se você preferir testar chamadas de API sem viver em um terminal, este é um loop mais limpo do que "curl-e-olhar-com-dificuldade"; o passo a passo para testar APIs sem Postman cobre o fluxo de trabalho geral.

Aqui está um loop focado para kimi-k3:

  1. Crie uma nova requisição HTTP no Apidog. Defina o método para POST e a URL para sua URL base mais /chat/completions.
  2. Armazene sua chave como uma variável de ambiente. Nas configurações de ambiente do Apidog, adicione KIMI_API_KEY, então defina o cabeçalho Authorization para Bearer {{KIMI_API_KEY}}. Agora o segredo é referenciado, não colado, e você pode alternar entre chaves de teste e produção trocando de ambiente.
  3. Cole um corpo JSON com "model": "kimi-k3" e seu array de messages. Envie e leia a resposta completa, incluindo o uso de tokens, para que você possa ver as contagens de cache-hit versus cache-miss em chamadas reais.
  4. Mude "stream": true e observe os eventos enviados pelo servidor chegarem como frames discretos. Ver os chunks data: brutos torna os bugs de streaming óbvios de uma forma que o iterador organizado do SDK não faz.
  5. Depure chamadas de ferramentas inspecionando o array tool_calls na resposta. Quando os argumentos voltam malformados, você pode ver se o modelo produziu JSON inválido ou se seu esquema era ambíguo, e corrigir a descrição ali mesmo.
  6. Teste A/B contra kimi-k2-7-code. Duplique a requisição, mude apenas o campo model, e compare a latência, qualidade da saída e custo no mesmo prompt. Essa é a maneira mais rápida e honesta de decidir se o raciocínio extra do K3 vale o salto de preço para sua tarefa.

Como o Apidog importa requisições compatíveis com OpenAI diretamente, você pode colar um comando cURL e obter uma requisição salva e reproduzível com cabeçalhos e corpo já preenchidos. A partir daí, ela se torna um caso de teste compartilhado que sua equipe pode executar novamente sempre que o Kimi lançar uma atualização. Se seu agente se comunica com o modelo através do MCP, o guia de depuração visual com o cliente MCP do Apidog mostra como rastrear essas chamadas também. Baixe o Apidog se quiser seguir este loop com sua própria chave.

Casos de uso no mundo real

Alguns padrões se encaixam perfeitamente naquilo para o qual o kimi-k3 foi construído:

Em cada um desses casos, o fluxo de trabalho é o mesmo: construa a requisição com o SDK, verifique o comportamento bruto no Apidog e, em seguida, conecte-o ao seu aplicativo assim que confiar no formato.

Conclusão

Chamar o Kimi K3 se resume a três configurações em um cliente compatível com OpenAI: a URL base do seu console, sua chave de API e model="kimi-k3". A partir daí, streaming, chamadas de ferramentas, modo JSON, saída estruturada e reasoning_effort seguem o contrato de chat-completions que você já conhece. As duas coisas que valem a pena internalizar são a economia de caching, onde manter um prefixo estável transforma uma entrada de $3,00 em uma entrada de $0,30, e o trade-off honesto de que o K3 compra profundidade de raciocínio por um preço real, então direcione o trabalho rotineiro de alto volume para a linha K2.7. Construa a requisição em código, prove-a no Apidog, e você implementará o kimi-k3 sem surpresas.

FAQ

Qual é o ID do modelo da API para Kimi K3? É kimi-k3 na própria plataforma do Kimi. Se você o chamar via OpenRouter, o slug é moonshotai/kimi-k3. Você pode ver a listagem do modelo no OpenRouter em openrouter.ai/moonshotai/kimi-k3.

Qual URL base devo usar? Confirme-a no console em platform.kimi.ai, já que essa é a fonte da verdade para sua conta. O Kimi historicamente usou https://api.moonshot.ai/v1. No código, mantenha-o como uma variável base_url que você define a partir do console, em vez de codificá-lo diretamente.

O Kimi K3 é compatível com o SDK da OpenAI? Sim. A API segue o formato de chat-completions da OpenAI, então os SDKs oficiais Python e JavaScript da OpenAI funcionam após você alterar base_url e model. Campos específicos do provedor passam por extra_body.

Quanto custa a API do Kimi K3? $0,30 por milhão de tokens de entrada com cache-hit, $3,00 por milhão de tokens de entrada com cache-miss, e $15,00 por milhão de tokens de saída. Estruturar prompts para reutilização de cache é a maior alavanca na sua conta. O guia de preços do Kimi K3 detalha os números.

O que o cache de contexto realmente faz? Quando os tokens iniciais da sua requisição correspondem a uma requisição anterior, o endpoint reutiliza o estado computado em vez de recalculá-lo, o que reduz o custo de entrada de $3,00 para $0,30 por milhão nessa porção. Mantenha seu prompt de sistema e contexto compartilhado na frente e idênticos em todas as chamadas para maximizar os hits.

Posso controlar o quanto o modelo "pensa"? Sim, através de reasoning_effort. O nível disponível hoje é max, que também é o padrão; a Moonshot disse que outros níveis estão planejados. Um esforço maior custa mais tokens de saída e adiciona latência.

Devo usar Kimi K3 ou Kimi K2.7 Code? Use kimi-k3 quando precisar de raciocínio profundo, do contexto completo de 1M, ou de orquestração de ferramentas de agente. Para trabalho de codificação rotineiro de alto volume, a linha K2.7 mais barata costuma ser a melhor opção. A comparação Kimi K3 vs Kimi K2.7 Code e o guia da API Kimi K2.7 Code ajudam você a decidir.

Como depuro uma resposta quebrada de streaming ou chamada de ferramenta? Envie a requisição bruta no Apidog com "stream": true e leia os eventos enviados pelo servidor quadro a quadro, ou inspecione o array tool_calls para ver se o modelo retornou JSON malformado. Armazenar sua chave como uma variável de ambiente a mantém fora do corpo da requisição enquanto você testa.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar