Skip to main content

​
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

Preços e cotas mudam regularmente. Sempre confirme os números atuais em z.ai/subscribe e docs.z.ai antes de escolher um plano.

​
GLM Coding Plan (assinatura)

  • 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

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

​
Criando uma Chave de API

Uma conta Z.AI é necessária para criar uma chave de API.
  1. Faça login em z.ai.
  2. Adquira um plano GLM Coding Plan em 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.
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/.

​
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). 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:
  • Desabilitar thinking — para revisões mais rápidas/baratas em PRs pequenos:
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 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.
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:

​
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:
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:
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 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

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