Kimi K3.1 Pro API: Endpoints, Chamada de Ferramentas, Cache e Erros

A API do Kimi K3.1 Pro é executada em https://api.moonshot.ai/v1 com os IDs de modelo kimi-k3.1-pro e kimi-k3.1-pro-highspeed. Ela fala três formatos de protocolo: OpenAI Chat Completions, a Responses API e Anthropic Messages, portanto os SDKs que você já usa funcionam com uma URL base alterada. O modelo é desbloqueado após uma recarga mínima de $1.

Esta é a referência para código de produção. Para sua primeira chamada, streaming e as configurações do Codex ou Claude Code, leia como usar o Kimi K3.1 Pro; para custos, consulte preços do Kimi K3.1 Pro. Os fatos vêm do guia de início rápido do K3.1 Pro da Moonshot e dos documentos vinculados, lidos em 24 de outubro de 2026.

Responses API, Anthropic API e Chat Completions do Kimi K3.1 Pro

A Moonshot expõe o K3.1 Pro por meio de três superfícies de API. Escolha a que sua biblioteca de cliente ou agente já fala; o modelo, a chave e a cobrança são os mesmos nas três.

Elas diferem na forma como você define o TTL do cache e onde o uso é registrado (veja o cache abaixo). Vindo do K3? Nosso guia da API do Kimi K3 ainda se aplica; o K3.1 Pro é um K3 pós-treinado com o mesmo contexto de 1.048.576 tokens.

Chave de API do Kimi K3.1 Pro: desbloqueie e verifique o acesso

Você precisa de uma conta com saldo e de uma chave do produto correto. Quatro passos:

1. Faça uma recarga de pelo menos $1 na plataforma da API Kimi. O K3.1 Pro é um modelo de ponta e é desbloqueado somente após uma recarga bem-sucedida.
2. Crie uma chave no console de chaves de API e exporte-a como MOONSHOT_API_KEY.
3. Confirme que o modelo está visível para essa chave com GET /v1/models.
4. Chame kimi-k3.1-pro a partir do código.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

Se o modelo não estiver listado, resolva isso primeiro. Kimi API, Kimi Code e Kimi Membership são produtos separados: uma chave do Kimi Code não funcionará no endpoint da API, e uma assinatura não se transforma em saldo de API.

Parâmetros de requisição que importam para o K3.1 Pro

A maioria dos parâmetros da OpenAI se comporta como você esperaria. Estes são os que diferem ou pegam as pessoas de surpresa:

Os tokens de raciocínio contam para o seu uso, então use "low" para classificação e extração. O Preserved Thinking está sempre ativado, então toda mensagem do assistente volta com seu reasoning_content intacto (guia de modelos de raciocínio).

Chamada de ferramentas do Kimi K3.1 Pro: um loop completo em Python

Um loop de ferramentas de produção no K3.1 Pro segue quatro regras da documentação da Moonshot:

• Force uma chamada de ferramenta no primeiro turno com tool_choice="required", depois mude para "auto".
• Anexe a mensagem completa do assistente, incluindo reasoning_content e tool_calls.
• Envie uma mensagem tool por tool_call_id.
• Limite o número de turnos para que um modelo confuso não entre em loop infinito.

import json, os
from openai import OpenAI

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

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

O bug clássico é anexar msg.content em vez de msg, o que descarta tool_calls e reasoning_content.

Chamada de ferramentas em escala com search_tools

Quando seu agente tem dezenas ou centenas de ferramentas, não envie todas as definições em cada requisição. A melhor prática de chamada de ferramentas do K3 da Moonshot recomenda este fluxo:

1. Declare uma função search_tools (seu backend a implementa) mais algumas ferramentas essenciais.
2. Defina tool_choice: "required" no primeiro turno para que o modelo recupere antes de responder.
3. Injete as definições de ferramentas correspondentes por meio de uma mensagem system que carrega um campo tools.
4. Deixe o modelo chamar as ferramentas carregadas nos turnos seguintes, com tool_choice de volta em "auto".

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

As definições injetadas usam o formato de tools de nível superior e se aplicam a partir dessa mensagem em diante. O servidor não as retém, então mantenha a mensagem nas requisições posteriores. Nem alterar tool_choice nem anexar uma definição quebra o cache de prefixo.

Entrada de visão e vídeo

O K3.1 Pro aceita imagens e vídeo junto com texto e retorna texto. Faça com que content seja um array de partes: uma parte image_url (o exemplo do guia de início rápido envia uma data URL base64 e observa que URLs públicas de imagem não são suportadas) ou uma parte video_url que aponta para um arquivo enviado com um ID ms://.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

Passe content como a mensagem do usuário e exclua o arquivo com client.files.delete(video.id) quando terminar.

Cache de contexto em código

O cache é automático para prefixos repetidos com um TTL padrão de 5 minutos. Acertos de cache são cobrados a $0,20 por milhão de tokens contra $2,00 para entrada não armazenada em cache, e uma gravação de 1 hora custa $4,00 contra $2,00 por 5 minutos. Em um prefixo de 1M de tokens, o TTL de 1 hora se paga após dois acertos.

Coloque o conteúdo estável primeiro (prompt de sistema, definições de ferramentas, documentos), o conteúdo variável por último, e nenhum timestamp no prefixo. Com o SDK openai, passe o TTL por meio de extra_body:

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

A API da Anthropic define o TTL com um campo cache_control de nível superior; marcadores dentro das mensagens são ignorados:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

Onde o uso do cache aparece depende da superfície:

Ao fazer streaming de Chat Completions, defina stream_options.include_usage=true para obter o uso no bloco final. Cada acerto renova o TTL, que é fixado na primeira gravação. Regras completas: o guia de cache de contexto.

Erros e correções da API do Kimi K3.1 Pro

A maioria das falhas se encaixa em seis padrões. Verifique error.type em todo 429, porque a correção depende dele.

Fique atento às tentativas novamente. O SDK da OpenAI tenta novamente 2 vezes por padrão em erros de conexão, 408, 409, 429 e 5xx, então uma chamada pode se tornar três requisições contra seu RPM. Em um nível baixo, reduza o max_retries do cliente e faça backoff por conta própria com base em error.type. Requisições interrompidas por um 429 não são cobradas.

Se um agente de terceiros falhar, chame a API diretamente com a mesma chave, endpoint e modelo. Se isso funcionar, a ferramenta é o problema. Consulte a página de solução de problemas e os códigos de erro.

Limites de taxa do Kimi K3.1 Pro por nível

Sua recarga acumulada define seu nível na página de limites:

O Tier0 permite 3 requisições por minuto, e cada turno de um loop de ferramentas é uma requisição. Uma execução de agente com cinco turnos já passa de um minuto nesse nível, então reserve $10 acumulados antes de testar agentes a sério.

Faça testes de contrato da API Kimi com o Apidog CLI

Um teste de contrato detecta o dia em que seu loop de ferramentas para de receber tool_calls de volta. Deixe seu agente de programação construí-lo com o Apidog CLI. Instale e faça login uma vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

Em seguida, instrua o Claude Code, o Codex ou qualquer agente que você use:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

O agente lê o esquema, valida seu payload e executa o caso:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

Os casos de teste precisam de uma categoria válida; apidog test-case category --project <projectId> as lista. Depois que a execução passar, troque -r cli,json por -r junit com --out-dir e a mesma verificação controla seu CI, como mostra nosso guia de CI/CD do Apidog CLI. A configuração do agente está em Apidog CLI no Claude Code. O plano gratuito do Apidog cobre até 4 usuários.

Perguntas frequentes

Qual é a URL base da API do Kimi K3.1 Pro?

https://api.moonshot.ai/v1 para Chat Completions e a Responses API, e https://api.moonshot.ai/anthropic para a Messages API compatível com Anthropic.

A API do Kimi K3.1 Pro suporta o parâmetro thinking?

Não. O raciocínio está sempre ativado. Controle-o com o campo reasoning_effort de nível superior ("low", "high" ou "max").

Por que recebo 429 logo após fazer uma recarga?

Leia error.type. engine_overloaded_error é capacidade do servidor e uma recarga não vai resolver. rate_limit_reached_error significa os limites do seu nível, e o Tier0 permite apenas 3 RPM.

Como sei se o cache está funcionando?

Um campo de leitura de cache diferente de zero em usage significa um acerto: prompt_tokens_details.cached_tokens em Chat Completions ou cache_read_input_tokens em Messages.

Existe um nível gratuito da API do Kimi K3.1 Pro?

Não. A API exige uma recarga mínima de $1. O chat gratuito no app Kimi é a rota de $0, abordada em como usar o Kimi K3.1 Pro gratuitamente. Para contexto sobre o modelo, veja o que é o Kimi K3.1 Pro.