> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Moonshot (Kimi) - Inferência Compatível com OpenAI

> Aprenda como conectar os modelos Kimi K2.6 da Moonshot AI ao Kodus — via Moonshot Developer API ou Kimi Code Plan.

## Como o Moonshot funciona

A Moonshot AI publica a família de modelos **Kimi** (K2, K2.5, K2.6, K2.6 Coding). O Kimi é particularmente forte em compreensão de código de contexto longo e fluxos agênticos, e a API é totalmente compatível com OpenAI — o Kodus pode se comunicar com ela via o provedor **OpenAI-compatible**. O Kodus também tem um provedor **Moonshot** dedicado, que se conecta pelo endpoint compatível com Anthropic da Moonshot (`https://api.moonshot.ai/anthropic`).

A Moonshot oferece **dois caminhos** para a mesma família de modelos, cada um com seu próprio endpoint:

* **Developer API** (`platform.moonshot.ai`) — pay-per-token, cobrado por uso. A simultaneidade escala com seu tier de recarga.
* **Kimi Code Plan** (`kimi.com/code`) — assinatura com um **endpoint de codificação dedicado**. Preço fixo, simultaneidade limitada (30 simultâneas).

> [!NOTE]
>
> As assinaturas do chat de consumidor Kimi.com da Moonshot (Andante, Moderato, etc.) são separadas de ambos os caminhos de API. Assinaturas de chat **não** concedem acesso à API. O Kimi Code Plan é a assinatura específica para API.

A Moonshot também opera uma plataforma exclusiva para a China (`platform.moonshot.cn`, URL base `https://api.moonshot.cn/v1`) cobrada em CNY. Use apenas se você opera dentro da China continental.

## Visão geral dos planos

### Kimi Code Plan (assinatura)

| Atributo | Valor |
| - | - |
| **Endpoint** | `https://api.kimi.com/coding/v1` |
| **Simultaneidade** | Limitada a 30 requisições simultâneas |
| **Cobrança** | Assinatura de taxa fixa |
| **Chaves de** | [kimi.com/code](https://www.kimi.com/code) |

### Developer API (pay-per-token)

| Modelo | Preço (1M tokens entrada / saída) | Janela de Contexto | Notas |
| - | - | - | - |
| **Kimi K2.6 Coding** `recomendado` | \~$0,60 / $2,50 | \~256k tokens | Mais recente, ajustado para revisão de código. |
| **Kimi K2.5** | $0,60 / $2,50 | \~256k tokens | Geração anterior, ainda capaz. |
| **Kimi K2 (0905)** | tier inferior | \~128k tokens | Modelo estável de propósito geral. |

Endpoint da Developer API: `https://api.moonshot.ai/v1` (internacional). A simultaneidade escala com o tier de recarga — Tier 1 (\$10 de recarga) começa em \~50 simultâneas, até \~1000 simultâneas no Tier 5.

## Criando uma Chave de API

> [!WARNING]
>
> Uma conta Moonshot é necessária para criar uma chave de API.

> [tab] Assinante do Kimi Code Plan
>
> 1. Vá para [kimi.com/code](https://www.kimi.com/code) e assine o plano.
>
> 2. Abra a área de gerenciamento de chaves da sua assinatura.
>
> 3. Crie uma chave do Kimi Code e copie-a.
>
> > [!NOTE]
> >
> > Chaves do Kimi Code funcionam apenas contra `https://api.kimi.com/coding/v1`. Elas retornarão 401 se enviadas para `api.moonshot.ai`.

> [tab] Developer API (pay-per-token)
>
> 1. Faça login em [platform.moonshot.ai](https://platform.moonshot.ai) (ou [platform.moonshot.cn](https://platform.moonshot.cn) se você opera dentro da China continental).
>
> 2. Adicione um método de pagamento — a Moonshot pode conceder um pequeno saldo inicial quando você adicionar a cobrança pela primeira vez.
>
> 3. Abra a seção **API Keys** em [platform.moonshot.ai/console/api-keys](https://platform.moonshot.ai/console/api-keys).
>
> 4. Clique em **Create API Key**, dê um nome descritivo (ex.: `kodus-prod`) e copie a chave imediatamente.
>
> > [!NOTE]
> >
> > Chaves da Developer API funcionam apenas contra `api.moonshot.ai/v1` (internacional) ou `api.moonshot.cn/v1` (China). As chaves **não** são portáteis entre regiões.

## Configurar o Moonshot no Kodus

O fluxo principal é a página **AI providers** no Kodus Cloud. Usuários self-hosted que preferem fixar o provedor no nível do processo podem usar variáveis de ambiente.

### Opção 1 — Provedor Moonshot no Kodus Cloud (recomendado para a Developer API)

**1. Abrir AI providers e escolher Moonshot**

Na barra lateral, abra **AI providers** ([app.kodus.io/byok](https://app.kodus.io/byok)). Na aba **Providers**, clique no card **Moonshot** (em **Connect your first provider**, ou em **Add another provider** se você já conectou um).

**2. Colar sua chave de API e escolher o modelo**

Cole sua chave da Developer API de [platform.moonshot.ai](https://platform.moonshot.ai/console/api-keys) no card **API key**. O seletor **Model** então carrega os modelos da Moonshot — escolha um (ex.: `kimi-k2.6`) ou selecione **Type model manually**. O Kodus preenche o endpoint `https://api.moonshot.ai/anthropic` para você; este card não tem seletor de plano nem campo de URL base, então para uma chave do Kimi Code Plan (ou da plataforma chinesa) use a Opção 2 abaixo.

**3. Test & save**

Clique em **Test & save**. O Kodus testa a conexão e salva a configuração em caso de sucesso. 401 significa que a chave não corresponde ao endpoint.

### Ajustar reasoning (opcional)

**Thinking / Reasoning** fica em **Advanced (optional)**. Para o Kimi, qualquer nível diferente de Off emite `thinking: { type: "enabled" }`. Para sobrescrever, mude **Thinking / Reasoning** para **Custom** e cole um destes:

* **Desabilitar thinking** para revisões mais rápidas/baratas em PRs pequenos:

  ```json theme={null}
  {
    "thinking": { "type": "disabled" }
  }
  ```

* **Forçar um budget de tokens específico** (se a Moonshot adicionar suporte a `budget_tokens` no seu tier):

  ```json theme={null}
  {
    "thinking": { "type": "enabled", "budget_tokens": 25000 }
  }
  ```

> [!NOTE]
>
> Não é necessário envolver em namespace — o Kodus envolve as opções sob o namespace do provider ativo antes de enviar. Veja [main BYOK doc → Custom JSON override](https://docs.kodus.io/pt-BR/how_to_use/byok.md#sobrescrita-via-json-customizado) para detalhes.

### Ajustar simultaneidade

* **Kimi Code Plan**: defina **Max concurrent requests** (em **Advanced (optional)**) como `30` (o limite documentado). Ir além retorna 429.
* **Developer API**: comece vazio (sem limite). Seu limite real escala com seu tier de recarga — Tier 1 (\~$10 de recarga) permite ~50 simultâneas; Tier 5 (~$3000) permite \~1000. Reduza explicitamente se você ver 429s no momento da revisão.

> [!NOTE]
>
> Na aba **Routing**, defina o Kimi como **Model for all tasks** e um modelo OpenAI ou Anthropic como **Fallback (optional)** — se a Moonshot retornar 429 ou 402, o Kodus faz failover automaticamente.

### Opção 2 — Endpoint OpenAI-compatible

Para o Kimi Code Plan, a plataforma chinesa ou o endpoint OpenAI-compatible da Moonshot, abra **AI providers**, escolha **OpenAI-compatible** em **Custom** na aba **Providers** e preencha:

| Campo | Valor |
| - | - |
| **Base URL** | `https://api.moonshot.ai/v1` (Developer API) `https://api.kimi.com/coding/v1` (Kimi Code Plan) `https://api.moonshot.cn/v1` (apenas China continental) |
| **Model** | `kimi-k2.6`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2-0905`, `kimi-k2` |
| **API key** | sua chave Moonshot ou Kimi Code (correspondente à URL base acima) |
| **Max concurrent requests** (em **Advanced (optional)**) | `30` no Kimi Code Plan; deixe vazio na Developer API (escala com o tier de recarga) |

### Opção 3 — Self-hosted (variáveis de ambiente)

Se você executa o Kodus em Fixed Mode (provedor global único, sem BYOK por organização), configure a Moonshot no `.env` dos seus containers de API e worker:

```env theme={null}
# Moonshot (Kimi) configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="kimi-k2.6"
API_OPENAI_FORCE_BASE_URL="https://api.moonshot.ai/v1"    # or https://api.kimi.com/coding/v1 for Kimi Code Plan
API_OPEN_AI_API_KEY="your-moonshot-or-kimi-code-api-key"
```

> [!NOTE]
>
> Este caminho só é necessário para instalações self-hosted do Kodus que desabilitam deliberadamente o BYOK. Se o BYOK estiver habilitado na sua instância self-hosted, prefira a **Opção 1** ou a **Opção 2** — a página **AI providers** funciona da mesma forma que no Cloud.

Reinicie os containers de API e worker após editar o `.env`, e verifique a integração:

```bash theme={null}
docker-compose logs api worker | grep -iE "moonshot|kimi"
```

Para a configuração completa self-hosted (domínios, chaves de segurança, banco de dados, webhooks, proxy reverso), siga o [guia de implantação em VM genérica](https://docs.kodus.io/pt-BR/how_to_deploy/deploy_kodus/generic_vm.md) e substitua apenas o bloco de LLM pelo acima.

## Escolhendo entre Kimi Code Plan, Developer API e agregadores

* **Kimi Code Plan** — custo previsível de taxa fixa, limite de 30 simultâneas, endpoint dedicado `api.kimi.com/coding/v1` otimizado para fluxos de codificação. Melhor para times em regime estável com volume previsível de PRs.
* **Moonshot Developer API** — pay-per-token, simultaneidade escala com o tier de recarga, maior flexibilidade. Melhor para cargas variáveis.
* **Proxy OpenRouter** — se você quer uma relação única de cobrança para muitos provedores, o OpenRouter expõe modelos Kimi com uma pequena margem de roteamento. Escolha isso quando o Kimi é parte de uma frota de múltiplos provedores, não uma carga principal.

## Solução de problemas

> [accordion] 401 após Test — chave não corresponde ao endpoint
>
> * Chaves do Kimi Code Plan funcionam apenas contra `api.kimi.com/coding/v1`.
> * Chaves da Developer API de `platform.moonshot.ai` funcionam apenas contra `api.moonshot.ai/v1`.
> * Chaves da Developer API de `platform.moonshot.cn` funcionam apenas contra `api.moonshot.cn/v1`.
> * O card **Moonshot** sempre usa `https://api.moonshot.ai/anthropic`, então precisa de uma chave de `platform.moonshot.ai`. Conecte chaves do Kimi Code Plan ou de `platform.moonshot.cn` via **OpenAI-compatible** com a **Base URL** correspondente.

> [accordion] Saldo insuficiente
>
> * A Developer API cobra pay-per-token. Se o saldo acabar, as requisições retornam HTTP 402.
> * Adicione fundos na seção de cobrança do console ou defina um limite mensal para evitar surpresas.
> * O Kimi Code Plan tem preço fixo, mas é limitado pelo seu limite de 30 simultâneas e janelas de cota — 429 significa que você atingiu um.

> [accordion] Modelo não encontrado
>
> * Confirme que o nome do modelo corresponde ao catálogo (`kimi-k2.6`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2-0905`, `kimi-k2`).
> * Verifique [platform.kimi.ai/docs](https://platform.kimi.ai/docs) para a lista atual — novas versões são lançadas regularmente.

> [accordion] Primeira resposta lenta
>
> * A primeira chamada após períodos de inatividade pode ter cold-start do lado da Moonshot.
> * Se a latência importa, `kimi-k2-0905` geralmente é mais rápido que as variantes K2.6 para revisões rotineiras.

> [accordion] Região / conectividade
>
> * Usuários fora da China devem sempre usar `api.moonshot.ai` ou `api.kimi.com`. `api.moonshot.cn` pode ser inacessível ou ter taxa limitada fora da China continental.
> * Confirme que o HTTPS de saída para o endpoint escolhido é permitido na sua implantação do Kodus.

## Relacionados

* [Plataforma Moonshot (internacional)](https://platform.moonshot.ai)
* [Kimi Code Plan](https://www.kimi.com/code)
* [Documentação da API Kimi](https://platform.kimi.ai/docs)
* [Visão geral do BYOK](https://docs.kodus.io/pt-BR/how_to_use/byok.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.