A API Moonshot é a interface de modelos da plataforma aberta da Moonshot AI, ou seja, a plataforma de desenvolvedores por trás do Kimi. A cobrança é por uso de tokens, sem plano por assinatura. Muitas equipes erram o orçamento em dois pontos: continuam chamando o modelo moonshot-v1, que já foi descontinuado, ou misturam entrada, escrita de cache, saída e retentativas em um único preço médio. Este artigo detalha a estrutura de cobrança com base em documentos públicos de outubro de 2026; preços concretos seguem a página de preços do site e a documentação do fornecedor.

Nota: Moonshot e Kimi são marcas de seus titulares. Este artigo é apenas uma explicação técnica e não representa vínculo de subordinação ou representação com os titulares. Lista de modelos, comprimento de contexto e regras de cobrança podem mudar; confira novamente as páginas do fornecedor antes de comprar.

1. Distinga "modelos atuais" e "modelos descontinuados"

Até outubro de 2026, a documentação da plataforma lista como principais modelos kimi-k3, kimi-k2.6, kimi-k2.7-code e kimi-k2.7-code-highspeed. A antiga série moonshot-v1 saiu de linha: moonshot-v1-8k, -32k, -128k, -auto e as versões de visualização correspondentes foram descontinuadas em 31 de agosto de 2026, junto com kimi-k2.5. As versões de visualização anteriores kimi-k2 e kimi-latest também já foram encerradas.

Modelo Contexto Estrutura de cobrança Situação e observações
kimi-k3 1.048.576 Entrada, acerto de cache, escrita de cache, saída Principal atual; o fornecedor recomenda como destino de migração
kimi-k2.6 262.144 Entrada, acerto de cache, saída Uso geral e multimodal; comum em cenários sensíveis a custo
kimi-k2.7-code 262.144 Entrada, acerto de cache, saída Geração de código, perguntas sobre repositório e agentes
kimi-k2.7-code-highspeed 262.144 Entrada, acerto de cache, saída Tarefas de código com baixa latência
moonshot-v1-8k/32k/128k Conforme o nome Faixas antigas por comprimento Descontinuados em 31/08/2026

Nomes de modelo de tutoriais antigos não devem ser copiados diretamente. O "8k" de moonshot-v1-8k era a própria faixa de contexto; a falha na chamada não é problema de Key, mas de modelo inexistente. Na migração, altere primeiro o nome do modelo e depois confira contexto e itens de cobrança; não faça apenas uma substituição de string.

2. Unidade de cobrança: uma requisição dividida em quatro itens

A fatura atual normalmente compõe-se de quatro tipos de token: entrada sem acerto de cache, entrada com acerto, escrita de cache e saída. A escrita de cache do K3 é cobrada separadamente por TTL de 5 minutos e de 1 hora; a página de preços da série K2 não lista escrita de cache como item próprio. A fórmula de uma requisição fica assim:

custo da requisição =
  tokens de entrada sem acerto × preço unitário sem acerto
+ tokens de entrada com acerto × preço unitário com acerto
+ tokens de escrita de cache × preço do TTL correspondente (somente K3)
+ tokens de saída × preço unitário de saída

A documentação do fornecedor traz uma conversão útil: em texto chinês padrão, cerca de 1,5 a 2 caracteres correspondem a 1 token. Multiplicar a contagem de caracteres pelo preço unitário subestima a entrada; para uma estimativa formal, use a interface POST /v1/tokenizers/estimate-token-count ou leia diretamente o usage da resposta.

Na Chat Completions, os campos de uso são usage.prompt_tokens e usage.completion_tokens; o detalhe de cache fica em usage.prompt_tokens_details.cached_tokens e cache_write_tokens. Na Messages API, input_tokens não inclui a parte de cache; a entrada total soma input_tokens, cache_read_input_tokens e cache_creation_input_tokens. Em streaming, configure stream_options.include_usage=true.

3. Como o cache é cobrado e por que não acerta

O cache de contexto funciona por correspondência de prefixo, não da conversa inteira. Qualquer mudança no prefixo impede a reutilização do conteúdo posterior àquele ponto. Comportamentos que quebram o prefixo incluem: inserir carimbo de tempo ou ID aleatório no prompt de sistema, reordenar definições de ferramentas a cada chamada, concatenar dinamicamente trechos da base de conhecimento e trocar a faixa de TTL. O cache também é isolado por organização; não há compartilhamento entre organizações.

No K3, a escrita de cache é cobrada na primeira gravação, com TTL fixo de 5 minutos ou 1 hora, sem troca de faixa depois da gravação; um acerto renova gratuitamente o TTL original e não cobra escrita novamente. As duas faixas de cache não se comunicam. Se o final do prefixo não completar um bloco de cache inteiro, essa parte normalmente é tratada como não acerto.

Cache não é um interruptor de "ligou, economizou"; é engenharia de prefixo. Coloque o prompt de sistema, as definições de ferramentas, os exemplos fixos e a parte comum da base de conhecimento no início; deixe as variáveis no final; e verifique a taxa de acerto com cached_tokens.

4. Custo de contexto longo: o caro é a retransmissão

O K3 suporta contexto de 1.048.576 tokens, e a série K2, 262.144 tokens. O K3 usa cobrança unificada por uso e não segue as faixas de 8k, 32k e 128k do antigo moonshot-v1, portanto não dá para estimar o K3 com a tabela antiga por faixa.

Contexto longo em si não é o problema; o problema é reenviar o mesmo material a cada rodada. Em uma consulta de 200 mil tokens sobre um documento, com dez perguntas seguidas e o texto completo em cada uma, o custo de entrada se acumula rapidamente; logs de ferramentas, corpo de páginas e resultados de código também permanecem no histórico e continuam sendo cobrados. O mais comum é: recuperar primeiro os trechos relevantes e depois pedir ao modelo para ler; usar resumo móvel em conversas de várias rodadas; transformar a parte estável em prefixo de cache; usar contexto longo apenas para o texto original que precisa ser mantido.

Contexto longo também amplia latência e taxa de falha. Requisições longas sem streaming estão mais sujeitas a timeout de gateway, e a retentativa gera novo consumo de entrada. Para tarefas longas, prefira saída em streaming e configure um timeout de leitura razoável.

5. Como retentativas e requisições com falha entram na conta

Os códigos de erro do fornecedor dividem o 429 em três tipos: rate_limit_reached_error é teto de concorrência, RPM, TPM ou TPD no nível da organização; exceeded_current_quota_error é saldo ou cota insuficiente; engine_overloaded_error é sobrecarga de capacidade do servidor. Apenas problema de saldo se resolve com recarga; sobrecarga de capacidade não desaparece só recarregando. Para 500 e 503, normalmente se recomenda tentar mais tarde; em timeout de gateway de requisições longas, é melhor mudar para streaming do que reenviar igual.

A documentação do fornecedor não promete que requisições com falha sejam gratuitas. O mais seguro é não presumir custo zero em retentativa, conciliar com logs de requisição e usage e contabilizar o número de tentativas separadamente. A política de retentativa pode seguir esta ordem:

  1. Classifique primeiro pelo código de erro; inadimplência, erro de parâmetro e falha de revisão de conteúdo não devem ser repetidos.
  2. Repita de forma limitada apenas 429 de limite, 500, 503 e interrupção de rede.
  3. Use backoff exponencial com jitter aleatório e respeite Retry-After.
  4. Defina teto de tentativas e duração total para não ocupar concorrência indefinidamente.
  5. Chamadas de ferramentas precisam de chave de idempotência ou tabela de deduplicação, para evitar pedido ou mensagem duplicados.
  6. Registre request_id, nome do modelo, consumo de tokens e número de tentativas para facilitar a conciliação.

6. Estimativa de orçamento: de tokens ao teto mensal

O orçamento não deve partir de "quanto custa por milhão de tokens" para trás, mas das tarefas reais. Escolha de 20 a 50 tarefas representativas, cobrindo os níveis simples, médio e complexo, e defina critérios de aceite; meça a entrada com a interface de estimativa, leia o usage de chamadas reais e compare modelos pelo "custo total para concluir uma tarefa aprovada".

import os
import requests

resp = requests.post(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    headers={"Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}"},
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Extraia este contrato em JSON: ..."}],
    },
    timeout=30,
)
print(resp.json()["data"]["total_tokens"])

Depois de estimar a entrada de uma chamada, acrescente quatro blocos: mensagens históricas, retornos de ferramentas, proporção de cache sem acerto e chamadas extras por retentativa. Para processamento offline em lote, vale avaliar a Batch API; a documentação do fornecedor indica cerca de 40% menos que a chamada síncrona, mas ela só suporta kimi-k2.7-code e kimi-k2.6 no momento, ainda sem kimi-k3.

O controle de orçamento pode ser feito em três camadas: orçamento diário e mensal por projeto — ao atingir o teto, o console recusa requisições daquele projeto, mas a execução pode ter cerca de dez minutos de atraso; separação por Key ou membro, para que um negócio não consuma a cota da organização inteira; conciliação semanal por modelo e cenário, para identificar as chamadas que mais crescem. O alerta de saldo só evita corte abrupto; não substitui o orçamento.

7. Ordem de redução de custo e hábito de conciliação

Não inverta a ordem. Primeiro faça governança de cache e de entrada, depois limite a saída e só então considere trocar de modelo; caso contrário, você apenas torna a resposta errada mais barata.

  1. Fixe o prompt de sistema, as definições de ferramentas e o prefixo da base de conhecimento, e valide cached_tokens.
  2. Use recuperação e resumo para reduzir o texto original enviado a cada chamada; resuma o histórico de forma móvel.
  3. Defina max_completion_tokens e exija JSON ou campos fixos, reduzindo saídas longas e abertas.
  4. Roteie por tarefa: kimi-k2.6 para uso geral, versão de código K2.7 para tarefas de código e K3 para materiais muito longos.
  5. Mude requisições longas para streaming, reduzindo retentativas por timeout e desconexão.
  6. Tarefas offline usam Batch API; tarefas em tempo real mantêm a interface síncrona.
  7. Concilie mensalmente por projeto, modelo e cenário, registrando à parte taxa de acerto de cache, número de tentativas e comprimento médio de saída.

A conciliação deve conter pelo menos: horário da chamada, projeto, modelo, tokens de entrada, tokens de acerto de cache, tokens de escrita de cache, tokens de saída, número de tentativas e request_id. Sem esses campos, qualquer diferença na fatura vira adivinhação.

Perguntas frequentes

Ainda é possível chamar moonshot-v1-8k?

Não. Toda a série moonshot-v1 foi descontinuada em 31 de agosto de 2026, e o fornecedor recomenda migrar para kimi-k3. Na migração, não basta trocar o nome: revise o comprimento de contexto, os itens de cobrança e os parâmetros de saída.

Por que o acerto de cache não funciona?

Verifique primeiro se o prefixo foi quebrado por carimbo de tempo, ID aleatório, ordenação dinâmica ou reordenação de ferramentas; depois confirme se o intervalo entre requisições não excedeu o TTL; por fim, confirme se escrita e leitura de cache estão na mesma organização e na mesma faixa de TTL. Use cached_tokens para decidir, não a intuição.

Contexto longo é sempre mais caro?

Não necessariamente, mas reenviar material longo costuma sair caro. O custo depende de quantas vezes a entrada se repete, da taxa de acerto de cache e do comprimento da saída. Reduza primeiro o escopo com recuperação e depois decida se vale usar contexto de um milhão de tokens.

Requisições com falha são cobradas?

A documentação do fornecedor não promete gratuidade em falhas. Não presuma custo zero em retentativa; confira com logs de requisição e usage e inclua o número de tentativas no custo por tarefa.

Onde ver os preços mais recentes?

Na página de preços do site e na documentação do Moonshot/Kimi. Preços, lista de modelos e regras de cache podem mudar; não use capturas de tela antigas.

Próximos passos

Crie primeiro uma Key de teste no ZSQH AI Gateway, execute um lote real de tarefas com kimi-k2.6 e kimi-k3, registre entrada, saída, acerto de cache e retentativas, e só então escolha o modelo principal e o orçamento mensal. Preços e modelos disponíveis seguem a página de preços.

Leitura relacionada: