Guia da API do Kimi K3: Python, visão, ferramentas e contexto de 1M

Guia de programador da API do Kimi K3

O Kimi K3 está disponível através da API Chat Completions compatível com OpenAI da Moonshot AI, com o ID de modelo kimi-k3. A API suporta raciocínio sempre ativo, streaming, imagens, vídeo carregado, JSON Schema estrito, ferramentas personalizadas, carregamento dinâmico de ferramentas e uma janela de contexto de 1 milhão de tokens.

Compatibilidade não significa comportamento idêntico. O K3 tem valores de amostragem fixos, exige o estado completo do assistente nos turnos seguintes de ferramentas e de conversa, e trata o raciocínio separadamente do conteúdo final. Este guia concentra-se nesses pormenores.

Disponibilidade e preços atualizados a 22 de julho de 2026. O Kimi K3 está disponível na Poyo.ai como kimi-k3, através da API Chat Completions compatível com OpenAI. O preço é de $2.28 por 1M de tokens de entrada e $11.40 por 1M de tokens de saída — 24% abaixo do preço oficial.

Requisitos

Precisas de:

Python 3.9 ou mais recente;
pacote Python openai na versão 1.0 ou posterior;
uma chave de API da Moonshot guardada fora do controlo de versões;
o URL base https://api.moonshot.ai/v1;
o ID de modelo kimi-k3.

Instala o SDK:

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

Define a chave na tua shell:

export MOONSHOT_API_KEY="your-key"

No PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Nunca coloques uma chave de produção num exemplo de código, num bundle do lado do cliente, num registo ou num repositório.

Faz o teu primeiro pedido ao Kimi K3

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Review this migration plan and list its three highest risks."}
    ],
)

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

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
    ]
  }'

Configura o esforço de raciocínio

O K3 usa sempre o modo de raciocínio. Configura o respetivo esforço através do campo de nível superior reasoning_effort:

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[
        {"role": "user", "content": "Find the flaw in this distributed lock design."}
    ],
)

Os valores suportados são:

Valor	Quando usar
`low`	Tarefas mais fáceis em que a latência e o volume de saída contam
`high`	Programação difícil, análise e planeamento de ferramentas
`max`	As tarefas mais difíceis e avaliações ao estilo de benchmark

O valor predefinido documentado é max. Não partas do princípio de que é a definição de produção mais barata. Avalia a taxa de sucesso, a latência e os tokens gerados em cada nível de esforço.

Faz streaming do raciocínio e do conteúdo final

As respostas em streaming expõem o raciocínio e o texto final em campos delta diferentes.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Store or process according to your product and provider policies.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)

Mantém o conteúdo final visível ao utilizador separado do processamento interno. Não analises saída estruturada a partir de reasoning_content.

Envia uma imagem ao Kimi K3

As mensagens de visão do K3 usam um array de objetos de conteúdo. Os URLs públicos de imagens não são suportados neste fluxo; codifica uma imagem local em base64.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()

response = 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": "Identify the three largest accessibility problems in this interface.",
                },
            ],
        }
    ],
)

Valida o tipo e o tamanho do ficheiro antes de codificares carregamentos de utilizadores. Evita registar payloads em base64.

Envia um vídeo ao Kimi K3

Carrega o vídeo através da Files API, referencia o ID devolvido com o esquema ms:// e elimina o ficheiro quando deixar de ser necessário.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")

try:
    response = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize the workflow and identify failed steps."},
                ],
            }
        ],
    )
finally:
    client.files.delete(video.id)

Devolve saída em JSON Schema estrito

Usa strict: true quando o código a jusante precisar de uma estrutura previsível.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "incident_risk",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "risk": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "owner": {"type": ["string", "null"]},
                },
                "required": ["risk", "severity", "owner"],
                "additionalProperties": False,
            },
        },
    },
)

result = json.loads(response.choices[0].message.content or "{}")

Analisa apenas o message.content final e valida-o de novo no código da aplicação.

Chama ferramentas personalizadas

A primeira resposta pode pedir uma ou mais ferramentas. Executa cada chamada permitida, acrescenta a mensagem completa do assistente e depois acrescenta um resultado de ferramenta correspondente para cada tool_call_id.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_build_status",
            "description": "Return the current build status for an allowed project.",
            "parameters": {
                "type": "object",
                "properties": {"project": {"type": "string"}},
                "required": ["project"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)
    # Authorize and validate before executing a real tool.
    tool_result = {"project": arguments["project"], "status": "passed"}
    messages.append(
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(tool_result),
        }
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)

Nunca executes comandos de shell arbitrários gerados pelo modelo sem um limite de permissões, validação de entradas, um ambiente restrito e um registo de auditoria.

Carrega ferramentas dinamicamente

O K3 permite colocar a definição completa de uma ferramenta numa mensagem system, no ponto em que ela passa a estar disponível. Mantém essa mensagem no histórico seguinte, porque o servidor não a retém por ti.

O carregamento dinâmico ajuda os grandes sistemas de agents a evitar o envio de todos os esquemas de ferramentas em cada turno. Também cria novos requisitos de gestão de estado: o modelo tem de ver a declaração exata ao interpretar resultados de ferramentas posteriores.

Usa a janela de contexto de 1M de tokens

Os contextos grandes são mais valiosos quando é preciso raciocinar em conjunto sobre provas distantes entre si. Usa-os de forma deliberada:

Mantém no início os repositórios ou corpora de documentos estáveis.
Acrescenta perguntas e resultados em vez de reescreveres o prefixo.
Acompanha em separado a entrada em cache e a entrada sem cache.
Obtém um subconjunto menor quando o corpus completo for desnecessário.
Estabelece identificadores de fonte para que a resposta final possa ser verificada.
Compacta apenas quando o teu cliente preservar todo o estado exigido pelo K3.

A cache automática não tem ID de cache nem um parâmetro de TTL normal. Os prefixos estáveis dão ao serviço a melhor oportunidade de acertar na cache.

Preserva o estado completo em várias interações

Esta é a regra de integração mais importante específica do K3.

Ao continuares uma conversa ou ao devolveres resultados de ferramentas, acrescenta a mensagem completa do assistente devolvida pela API. Não guardes apenas o content. A Moonshot avisa que o K3 foi treinado com histórico de raciocínio preservado e pode tornar-se instável se o harness descartar o histórico exigido ou mudar para o K3 a meio de uma sessão.

Guarda o estado da conversa em segurança, aplica limites de retenção e evita expor o estado oculto a utilizadores que não o devam ver.

Limites importantes da API do Kimi K3

O K3 tem sempre o raciocínio ativado.
reasoning_effort suporta low, high e max.
max_completion_tokens tem como valor predefinido 131 072 e pode ser definido até 1 048 576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 e frequency_penalty=0 são fixos; omite-os.
Os URLs públicos de imagens não são suportados em mensagens de visão.
Os pedidos de várias interações e de ferramentas têm de preservar a mensagem completa do assistente.
A Moonshot diz que a sua ferramenta de pesquisa na web está a ser atualizada e que, de momento, não é recomendada para produção.

Lista de verificação para produção

Mantém as chaves de API do lado do servidor.
Adiciona timeouts de pedidos e repetições limitadas.
Valida os argumentos das ferramentas e autoriza todas as ações.
Limita os turnos de ferramentas e a extensão da conclusão.
Preserva o estado completo do assistente do K3.
Valida o JSON estrito depois da geração.
Regista a entrada, a entrada em cache, a saída, a latência e os erros.
Evita mudar de modelo a meio de uma sessão do K3.
Adiciona limites comportamentais explícitos para reduzir a proatividade excessiva.
Testa com ferramentas avariadas, respostas parciais e históricos longos.

Lê os preços da API do Kimi K3 antes de escolheres os limites de contexto e de saída. Acompanha a página do modelo Kimi K3 para saberes a disponibilidade na Poyo.ai.

Perguntas frequentes

A API do Kimi K3 é compatível com a OpenAI?

Sim. A Moonshot disponibiliza um endpoint Chat Completions compatível com a OpenAI. As regras específicas do K3 para estado, raciocínio, amostragem e multimédia continuam a aplicar-se.

Qual é o ID de modelo do Kimi K3?

O ID de modelo oficial na API da Moonshot é kimi-k3.

O Kimi K3 suporta function calling?

Sim. Suporta ferramentas personalizadas, escolha obrigatória de ferramenta, resultados de ferramenta correspondentes e carregamento dinâmico de ferramentas.

O Kimi K3 consegue processar vídeo?

Sim. Carrega o vídeo através da Files API e referencia o respetivo ID de ficheiro ms:// num objeto de conteúdo de vídeo.

Como uso a janela de contexto de 1M?

Envia as mensagens e o conteúdo necessários no pedido normal ao modelo, mantém inalterados os prefixos estáveis para a cache automática e define limites de conclusão controlados.