A Kimi API é compatível com a interface da OpenAI, e a migração normalmente exige apenas três mudanças: URL base, API Key e nome do modelo. Mas, em 2026, alguns detalhes da interface pegam: modelos antigos saíram de linha, max_tokens foi descontinuado, o K3 usa por padrão a intensidade máxima de raciocínio e o consumo de streaming só aparece no último bloco.

Este artigo percorre a integração do zero: confirma site e protocolo, escolhe o modelo e faz a primeira chamada com curl e Python; ao final, traz checklist de migração e tabela de erros. Modelos e preços seguem a página de preços do site.

Nota: Moonshot e Kimi são marcas de seus titulares. Este artigo é apenas uma explicação técnica de integração. Lista de modelos, tamanho de contexto e regras de parâmetros podem mudar; vale a versão atual da documentação oficial.

1. Três confirmações antes de integrar

  1. Site: o site chinês usa platform.kimi.com; o internacional, platform.kimi.ai. Conta, saldo e chave são totalmente independentes entre os dois.
  2. Protocolo: a maioria dos projetos usa Chat Completions compatível com OpenAI; projetos que já têm o SDK da Anthropic podem usar a entrada compatível com Messages.
  3. Modelo: confirme primeiro quais modelos a conta enxuta vê e só depois escreva no código. Não copie tutoriais de meses atrás.

O domínio de requisição do site chinês é https://api.moonshot.cn; o internacional é https://api.moonshot.ai. Domínio e chave precisam corresponder; essa é uma das causas mais comuns de 401.

2. URL base e caminhos da interface

Protocolo URL base Caminho
OpenAI Chat Completions https://api.moonshot.cn/v1 /chat/completions
OpenAI Responses https://api.moonshot.cn/v1 /responses
Anthropic Messages https://api.moonshot.cn/anthropic /v1/messages
Lista de modelos https://api.moonshot.cn/v1 /models
Consulta de saldo https://api.moonshot.cn/v1 /users/me/balance

No site internacional, troque o domínio para api.moonshot.ai; os caminhos não mudam. No SDK da OpenAI, base_url vai até /v1, e o SDK acrescenta /chat/completions; no curl, é preciso escrever o caminho completo. Misturar os dois faz aparecer uma camada a mais ou a menos de /v1, o que resulta em 404.

A URL base da entrada compatível com Anthropic não leva /v1, diferente da entrada OpenAI. Ao usar o Claude Code ou outro SDK da Anthropic, preencha https://api.moonshot.cn/anthropic conforme o exemplo oficial.

3. Como escolher o nome do modelo

Modelo Contexto Tarefas indicadas Atenção
kimi-k3 1M Raciocínio complexo, engenharia de software, trabalho de conhecimento, documentos muito longos reasoning_effort padrão é max
kimi-k2.7-code 256K Geração de código, perguntas sobre repositório, agentes Melhor aderência a instruções em contexto longo
kimi-k2.7-code-highspeed 256K Complementação de baixa latência, programação interativa Mesmo modelo da versão padrão, mais rápido
kimi-k2.6 256K Conversa geral, extração, entrada de visão e texto Suporta modo com e sem raciocínio

Modelos antigos já saíram de linha: toda a série moonshot-v1 e o kimi-k2.5 deixaram de ser suportados em 31 de agosto de 2026; a série kimi-k2 deixou de ser suportada em 25 de maio de 2026; kimi-latest, antes disso. Projetos que ainda usam esses nomes devem migrar diretamente para kimi-k3 ou a série K2, sem procurar documentação antiga.

Não use K3 por padrão em tarefas genéricas. O K3 é capaz, mas a intensidade de raciocínio padrão é alta, aumentando latência e tokens de saída; classificação simples e extração de formato fixo costumam ficar melhores com kimi-k2.6. Tarefas de código pedem a série K2.7 Code.

4. Primeira chamada com curl

export MOONSHOT_API_KEY="sua-chave"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Responda apenas: integração concluída"}
    ],
    "max_completion_tokens": 64
  }'

Se retornar 200 com o conteúdo esperado, os quatro itens — chave, site, nome do modelo e caminho — estão corretos. Se retornar 401, verifique primeiro se site e chave correspondem; se retornar 404, verifique o nome do modelo e o /v1; se retornar 400, veja se a mensagem menciona contexto ou limite de saída.

5. SDK Python e streaming

Instale o SDK da OpenAI 1.0 ou superior e altere base_url e chave:

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explique em três pontos para que equipes um gateway de API é indicado"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nuso:", chunk.usage)

A resposta em streaming é SSE, cada linha começa com data: e termina com data: [DONE]. Com include_usage ativado, antes do fim chega um bloco extra com choices vazio e apenas usage. Se a conexão cair no meio, esse bloco pode não chegar; por isso, não dependa exclusivamente do cliente para contabilizar consumo.

6. max_completion_tokens e intensidade de raciocínio

max_tokens foi descontinuado; código novo usa max_completion_tokens. Ele indica o tamanho esperado da saída, não entrada mais saída. O padrão do K3 é 131072 e o máximo é 1048576; se entrada mais esse valor ultrapassar a janela de contexto, a requisição retorna invalid_request_error.

Duas regras práticas:

  • Em testes e tarefas de formato fixo, use valores baixos, como 256 a 1024, para evitar respostas longas.
  • Ao atingir o limite, finish_reason é length; no fim normal, é stop. Ao ver length, não retente diretamente: primeiro avalie se a saída realmente precisa ser maior ou se o prompt está aberto demais.

O K3 também tem o parâmetro de nível superior reasoning_effort, com opções low, high e max, padrão max. Em tarefas simples, low reduz latência e consumo; raciocínio complexo pede valores maiores. Com o SDK da OpenAI, se a versão não tiver o parâmetro embutido, envie via extra_body. O raciocínio do K3 fica em reasoning_content e deve ser devolvido integralmente em conversas de vários turnos e chamadas de ferramenta.

7. Migrar da OpenAI ou do Moonshot antigo

  1. Mapeie todos os nomes de modelo antigos no código e na configuração e monte uma tabela de substituição.
  2. Altere base_url: site chinês https://api.moonshot.cn/v1, internacional https://api.moonshot.ai/v1.
  3. Troque para a chave do site correspondente; não reutilize entre sites.
  4. Substitua os nomes de modelo, priorizando kimi-k3 ou os modelos atuais da série K2.
  5. Troque max_tokens por max_completion_tokens.
  6. Troque a configuração thinking do K2.x por reasoning_effort no K3; não envie os dois juntos.
  7. Acrescente stream_options={"include_usage": True} nas requisições em streaming.
  8. Rode regressão com o mesmo lote de tarefas reais e registre qualidade, latência, finish_reason e consumo.
  9. Mantenha a configuração antiga por um ciclo de release e só remova após confirmar.

Não faça a migração total de uma vez. Troque primeiro o ambiente de teste, depois negócios de baixo risco e, por fim, o caminho crítico, mantendo um interruptor de rollback em cada etapa.

8. Tabela de erros comuns

Código Tipo de erro Causa comum Tratamento
400 invalid_request_error Parâmetro errado, contexto longo demais, limite de saída fora da faixa Corrigir a requisição
400 content_filter Entrada ou saída acionou segurança de conteúdo Ajustar o prompt
401 invalid_authentication_error Chave inválida, site incompatível Trocar a chave ou o domínio
404 resource_not_found_error Nome de modelo ou caminho errado Consultar a lista de modelos
429 rate_limit_reached_error Concorrência, RPM, TPM ou TPD acima do limite Reduzir ritmo ou subir de nível
429 exceeded_current_quota_error Inadimplência ou saldo insuficiente Recarregar
504 Gateway Time-out Requisição longa sem streaming esperou demais Usar streaming

Requisições sem streaming podem retornar 504 se o servidor esperar mais de 900 segundos. Para geração de textos longos, análise de documentos extensos e agentes de código, prefira streaming: o cliente recebe dados continuamente e evita desperdício de "esperar o timeout para tentar de novo".

Perguntas frequentes

Até que nível vai a URL base?

No SDK da OpenAI, use https://api.moonshot.cn/v1, sem /chat/completions. No curl, escreva o caminho completo https://api.moonshot.cn/v1/chat/completions. No SDK da Anthropic, use https://api.moonshot.cn/anthropic.

Por que max_tokens não tem efeito?

O parâmetro foi descontinuado e alguns modelos o ignoram ou retornam erro. Use max_completion_tokens e lembre que ele é limite de saída, não limite de entrada mais saída.

Por que o K3 responde mais devagar que o esperado?

O reasoning_effort padrão do K3 é max, o que faz um raciocínio mais profundo. Em tarefas simples, use low ou high e limite o tamanho da saída; isso costuma melhorar bastante a latência.

Por que não há usage depois do streaming?

É preciso definir stream_options={"include_usage": True}. Mesmo assim, se a conexão cair, o último bloco pode não chegar; em produção, contabilize também no servidor.

O que mais muda ao migrar da OpenAI?

A maior parte do código muda apenas URL base, chave e nome do modelo. Verifique também max_tokens, usage em streaming, mapeamento de tipos de erro e política de retry, especialmente o tratamento de 429.

Próximo passo

Crie uma chave de teste no ZSQH AI Gateway, rode uma tarefa real com kimi-k3 e outra com kimi-k2.6, confirme o caminho e depois conecte produção. Modelos e cobrança seguem a página de preços.

Leituras relacionadas: