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

Guia para desenvolvedores da API Kimi K3

O Kimi K3 está disponível por meio da API Chat Completions compatível com OpenAI da Moonshot AI, usando o ID de modelo kimi-k3. A API oferece raciocínio sempre ativado, streaming, imagens, vídeos enviados, 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 possui valores de amostragem fixos, exige o estado completo do assistente em turnos posteriores de ferramentas e conversas, e trata o raciocínio separadamente do conteúdo final. Este guia se concentra nesses detalhes.

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

Requisitos

Você precisa de:

Python 3.9 ou superior;
pacote Python openai versão 1.0 ou superior;
uma chave de API da Moonshot armazenada fora do controle de versão;
a URL base https://api.moonshot.ai/v1;
ID do modelo kimi-k3.

Instale o SDK:

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

Defina a chave no seu shell:

export MOONSHOT_API_KEY="your-key"

No PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Nunca coloque uma chave de produção em exemplos de código, pacotes no lado do cliente, logs ou repositórios.

Faça sua primeira solicitação 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."}
    ]
  }'

Configure o esforço de raciocínio

O K3 sempre usa o modo de pensamento. Configure seu esforço por meio 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	Use para
`low`	Tarefas mais simples em que latência e saída são importantes
`high`	Codificação difícil, análise e planejamento de ferramentas
`max`	As tarefas mais complexas e avaliações no estilo benchmark

O padrão documentado é max. Não presuma que essa é a configuração de produção mais econômica. Avalie taxa de sucesso, latência e tokens gerados em cada nível de esforço.

Transmita raciocínio e conteúdo final em streaming

As respostas em streaming expõem o raciocínio e o texto final por meio de 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)

Mantenha o conteúdo final voltado ao usuário separado do processamento interno. Não analise saída estruturada a partir de reasoning_content.

Envie uma imagem para o Kimi K3

As mensagens de visão do K3 usam uma matriz de objetos de conteúdo. URLs públicas de imagens não são suportadas nesse fluxo; codifique uma imagem local como 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.",
                },
            ],
        }
    ],
)

Valide o tipo e o tamanho do arquivo antes de codificar uploads de usuários. Evite registrar cargas base64 em logs.

Envie um vídeo para o Kimi K3

Envie o vídeo pela API Files, faça referência ao ID retornado usando o esquema ms:// e exclua o arquivo quando ele não for mais 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)

Retorne saída com JSON Schema estrito

Use strict: true quando o código posterior 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 "{}")

Analise apenas o message.content final e valide novamente no código da aplicação.

Chame ferramentas personalizadas

A primeira resposta pode solicitar uma ou mais ferramentas. Execute cada chamada permitida, adicione a mensagem completa do assistente e depois adicione 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 execute comandos shell arbitrários gerados pelo modelo sem uma barreira de permissão, validação de entrada, ambiente limitado e trilha de auditoria.

Carregue ferramentas dinamicamente

O K3 permite colocar uma definição completa de ferramenta em uma mensagem system no momento em que ela se torna disponível. Mantenha essa mensagem no histórico posterior, pois o servidor não a mantém para você.

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

Use a janela de contexto de 1M tokens

Contextos grandes são mais valiosos quando evidências distantes precisam ser analisadas em conjunto. Use-os de forma planejada:

Mantenha repositórios estáveis ou conjuntos de documentos no início.
Adicione perguntas e resultados em vez de reescrever o prefixo.
Acompanhe entradas armazenadas em cache e sem cache separadamente.
Recupere um subconjunto menor quando o corpus completo não for necessário.
Estabeleça identificadores de origem para que a resposta final possa ser verificada.
Faça compactação apenas quando seu cliente preservar todo o estado necessário pelo K3.

O cache automático não possui ID de cache nem parâmetro TTL comum. Prefixos estáveis oferecem ao serviço a melhor oportunidade de utilizar o cache.

Preserve o estado completo de múltiplos turnos

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

Ao continuar uma conversa ou retornar resultados de ferramentas, adicione a mensagem completa do assistente retornada pela API. Não mantenha apenas content. A Moonshot alerta que o K3 foi treinado com o histórico de raciocínio preservado e pode ficar instável se o sistema remover histórico necessário ou alternar para o K3 no meio de uma sessão.

Armazene o estado das conversas com segurança, aplique limites de retenção e evite expor estados ocultos a usuários que não devem visualizá-los.

Limites importantes da API Kimi K3

O K3 sempre tem pensamento ativado.
reasoning_effort suporta low, high e max.
max_completion_tokens tem padrão de 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; omita-os.
URLs públicas de imagens não são suportadas para mensagens de visão.
Solicitações de múltiplos turnos e ferramentas devem preservar a mensagem completa do assistente.
A Moonshot informa que sua ferramenta de pesquisa na web está sendo atualizada e não é recomendada atualmente para produção.

Checklist de produção

Mantenha as chaves de API no servidor.
Adicione timeouts de solicitação e novas tentativas limitadas.
Valide argumentos de ferramentas e autorize cada ação.
Limite turnos de ferramentas e tamanho das conclusões.
Preserve o estado completo do assistente K3.
Valide JSON estrito após a geração.
Registre entrada, entrada em cache, saída, latência e erros.
Evite alternar modelos no meio de uma sessão K3.
Adicione limites comportamentais explícitos para reduzir proatividade excessiva.
Teste com ferramentas com falha, respostas parciais e históricos longos.

Leia Preços da API Kimi K3 antes de escolher limites de contexto e saída. Acompanhe a página do modelo Kimi K3 para disponibilidade no Poyo.ai.

Perguntas frequentes

A API Kimi K3 é compatível com OpenAI?

Sim. A Moonshot oferece um endpoint Chat Completions compatível com OpenAI. As regras específicas do K3 para estado, raciocínio, amostragem e mídia continuam aplicáveis.

Qual é o ID do modelo Kimi K3?

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

O Kimi K3 suporta chamadas de função?

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

O Kimi K3 pode processar vídeos?

Sim. Envie o vídeo pela API Files e faça referência ao seu ID de arquivo ms:// em um objeto de conteúdo de vídeo.

Como uso a janela de contexto de 1M?

Envie as mensagens e conteúdos necessários por meio da solicitação padrão do modelo, mantenha prefixos estáveis inalterados para cache automático e defina limites de conclusão controlados.