> ## 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.

# Z.AI (GLM Coding Plan) - Inferência por Assinatura

> Aprenda como conectar os modelos GLM do Z.AI — incluindo a assinatura GLM Coding Plan — ao Kodus.

## Como o Z.AI funciona

O Z.AI (desenvolvido pela Zhipu AI) serve a família de modelos GLM. É um dos poucos grandes provedores que oferece uma **assinatura de taxa fixa** para acesso à API: o **GLM Coding Plan** agrupa o uso de modelos a um preço mensal fixo, com limites de taxa aplicados em janelas de 5 horas e semanais em vez de cobrança por token.

Para cargas de trabalho de maior volume ou variáveis, o Z.AI também oferece acesso pay-per-token aos mesmos modelos em sua Developer API padrão.

Ambos os caminhos expõem um endpoint compatível com OpenAI, então o Kodus pode se comunicar com eles via o provedor **OpenAI-compatible**. O Kodus também tem um provedor **Z.ai** dedicado, que se conecta pelo endpoint compatível com Anthropic do Z.AI (`https://api.z.ai/api/anthropic`).

## Visão geral dos planos

> [!NOTE]
>
> Preços e cotas mudam regularmente. Sempre confirme os números atuais em [z.ai/subscribe](https://z.ai/subscribe) e [docs.z.ai](https://docs.z.ai/devpack/overview) antes de escolher um plano.

### GLM Coding Plan (assinatura)

| Plano | Preço (equivalente mensal) | Equivalente aproximado em valor de API | Simultaneidade |
| - | - | - | - |
| **Lite** | \~\$18/mês (cobrado trimestralmente) | \~15× a taxa mensal | \~1 simultânea |
| **Pro** | \~\$30/mês (cobrado trimestralmente) | \~20× a taxa mensal | \~1 simultânea |
| **Max** | \~\$80/mês (cobrado trimestralmente) | \~30× a taxa mensal | até 30 simultâneas |

* As cotas são redefinidas em uma janela deslizante de **5 horas** e uma janela **semanal** — planeje em torno do teto, não de um limite mensal.
* A cobertura inclui GLM-5.1, GLM-5-Turbo, GLM-5, GLM-4.5 e GLM-4.5-Air.
* Endpoints do Coding Plan: `https://api.z.ai/api/anthropic` (compatível com Anthropic — o que o provedor **Z.ai** no Kodus usa) e `https://api.z.ai/api/coding/paas/v4` (compatível com OpenAI). O endpoint padrão `/api/paas/v4/` não consome do Coding Plan.

### Developer API pay-per-token

| Modelo | Preço (1M tokens de entrada / saída) | Janela de Contexto |
| - | - | - |
| **GLM-5.1** `recomendado` | $0,95 / $3,15 | \~200k tokens |
| **GLM-5** | $0,72 / $2,30 | \~131k tokens |
| **GLM-4.5** | $0,60 / $2,20 | \~128k tokens |
| **GLM-4.5-Air** | tier inferior, otimizado para roteamento | \~128k tokens |

Endpoint padrão: `https://api.z.ai/api/paas/v4/` (compatível com OpenAI).

## Criando uma Chave de API

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

**Assinante do Coding Plan**

1. Faça login em [z.ai](https://z.ai).
2. Adquira um plano **GLM Coding Plan** em [z.ai/subscribe](https://z.ai/subscribe).
3. Abra a página de gerenciamento de chaves da sua assinatura e crie uma chave do Coding Plan.
4. Copie a chave — você não poderá vê-la novamente.

> [!NOTE]
>
> As chaves do Coding Plan estão vinculadas aos endpoints do Coding Plan (`/api/anthropic` e `/api/coding/paas/v4`). Elas **retornarão 401** se enviadas contra o endpoint padrão `/api/paas/v4/`.

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

1. Faça login em [z.ai](https://z.ai).
2. Abra a seção **API Keys** em [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).
3. Clique em **Create API Key**, dê um nome descritivo (ex.: `kodus-prod`) e copie a chave.

> [!NOTE]
>
> As chaves da Developer API estão vinculadas ao endpoint `/api/paas/v4/`.

## Configurar o Z.AI 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 Z.ai no Kodus Cloud (recomendado)

**1. Abrir AI providers e escolher Z.ai**

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

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

Cole sua chave Z.AI no card **API key** e digite o ID do modelo (ex.: `glm-5.1`) em **Model**. O Kodus preenche o endpoint `https://api.z.ai/api/anthropic` para você — o endpoint compatível com Anthropic que o Z.AI documenta para o GLM Coding Plan — então este card não tem seletor de plano nem campo de URL base. Para usar um endpoint OpenAI-compatible específico, use a Opção 2 abaixo.

**3. Definir simultaneidade (Coding Plan)**

O Kodus não pré-preenche a simultaneidade. No Coding Plan Lite/Pro, abra **Advanced (optional)** e defina **Max concurrent requests** como `1`; aumente até 30 se você está no Max.

**4. 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 GLM, qualquer nível diferente de Off emite `thinking: { type: "enabled" }`, o que é suficiente para a maioria das cargas. Dois casos para sobrescrever:

* **Forçar um budget de tokens específico** — mude **Thinking / Reasoning** para **Custom** e cole:

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

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

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

> [!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

* **Coding Plan Lite / Pro**: defina **Max concurrent requests** como `1`. Ir além retorna `429 Too much concurrency`.
* **Coding Plan Max**: aumente para `5` primeiro, até `30` se não vir 429s. O tier Max permite até 30 simultâneas.
* **Developer API**: comece vazio (sem limite). Reduza para `5` se vir erros de limite de taxa, depois ajuste.

> [!NOTE]
>
> Na aba **Routing**, defina o GLM 5.1 como **Model for all tasks** e um modelo OpenAI ou Anthropic como **Fallback (optional)** para que as revisões continuem rodando quando sua janela de 5 horas do Coding Plan se esgotar. O Kodus faz failover automaticamente.

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

Para conectar por um dos endpoints OpenAI-compatible do Z.AI, abra **AI providers**, escolha **OpenAI-compatible** em **Custom** na aba **Providers** e preencha:

| Campo | Valor |
| - | - |
| **Base URL** | `https://api.z.ai/api/coding/paas/v4` (Coding Plan) `https://api.z.ai/api/paas/v4/` (Developer API) |
| **Model** | `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.5`, `glm-4.5-air` |
| **API key** | sua chave Z.AI (correspondente à URL base acima) |
| **Max concurrent requests** (em **Advanced (optional)**) | `1` no Coding Plan Lite/Pro; até `30` no Max; deixe vazio na Developer API |

### 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 o Z.AI no `.env` dos seus containers de API e worker:

```env theme={null}
# Z.AI configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="glm-5.1"                                  # any GLM model you have access to
API_OPENAI_FORCE_BASE_URL="https://api.z.ai/api/coding/paas/v4"   # use /api/paas/v4/ for pay-per-token
API_OPEN_AI_API_KEY="your-z-ai-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** — 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 "z\.ai|glm"
```

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 o Coding Plan e pay-per-token

* Escolha o **Coding Plan** quando você tem um time previsível de revisores e quer um custo mensal fixo. As cotas de 5 horas e semanais equivalem a aproximadamente 15–30× o valor da assinatura em gastos equivalentes de API.
* Escolha **pay-per-token** quando seu tráfego for variável, quando você precisa de acesso ocasional às janelas de contexto maiores, ou quando quer que o custo escale linearmente com o volume de PRs.
* **Combine-os**: em **Routing**, use o Coding Plan como **Model for all tasks** e uma chave da Developer API (ou um provedor inteiramente diferente) como **Fallback (optional)** para cobrir picos que esgotam sua janela de assinatura.

## Solução de problemas

> **401 após Test — chave não corresponde ao endpoint**
>
> * Chaves do Coding Plan funcionam em `/api/anthropic` e `/api/coding/paas/v4`, não em `/api/paas/v4/`. Chaves da Developer API usam `/api/paas/v4/`.
> * O card **Z.ai** sempre usa `https://api.z.ai/api/anthropic`. Se sua chave só é válida em outro endpoint, conecte-a via **OpenAI-compatible** com essa **Base URL**.
> * Com **OpenAI-compatible**, confirme que a **Base URL** corresponde à origem da chave.

> **'Too much concurrency' no momento da revisão**
>
> * Os tiers Lite e Pro do Coding Plan geralmente permitem apenas **1 requisição simultânea**. Defina **Max concurrent requests** como `1`; aumente apenas no Max.
> * Reduza **Max concurrent requests** em Advanced settings se ainda estiver atingindo 429s.

> **Cota esgotada no Coding Plan**
>
> * As cotas são aplicadas em uma **janela deslizante de 5 horas** e uma **janela semanal**. Atingir uma delas retorna HTTP 429.
> * Verifique a cota restante no console do Z.AI.
> * Opções: aguarde a próxima janela, faça upgrade para um tier superior, ou tenha uma chave da Developer API configurada como o modelo **Fallback (optional)** em **Routing** para cobrir a lacuna.

> **Modelo não encontrado**
>
> * Verifique se o Model ID corresponde ao catálogo do Z.AI (`glm-5.1`, `glm-5-turbo`, `glm-5`, `glm-4.5`, `glm-4.5-air`).
> * O Coding Plan atualmente cobre apenas a família GLM — nomes de modelos não-GLM serão rejeitados.

> **Erros de conexão (timeout, DNS)**
>
> * Confirme que seu servidor pode alcançar `api.z.ai`.
> * Verifique os logs da API e do worker para o erro upstream exato.
> * Se você estiver em uma região com tráfego de saída restrito, roteie as requisições por um proxy reverso que sua infraestrutura permita.

## Relacionados

* [GLM Coding Plan (preços)](https://z.ai/subscribe)
* [Documentação para desenvolvedores Z.AI](https://docs.z.ai/devpack/overview)
* [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.