> ## 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) - Inferencia por Suscripción

> Aprende a conectar los modelos GLM de Z.AI — incluida la suscripción GLM Coding Plan — a Kodus.

## Cómo funciona Z.AI

Z.AI (desarrollado por Zhipu AI) sirve la familia de modelos GLM. Es uno de los pocos proveedores importantes que ofrece una **suscripción a tarifa plana** para el acceso a la API: el **GLM Coding Plan** agrupa el uso de modelos a un precio mensual fijo, con límites de tasa aplicados en ventanas de 5 horas y semanales en lugar de facturación por token.

Para cargas de trabajo de mayor volumen o variable, Z.AI también ofrece acceso de pago por token a los mismos modelos en su Developer API estándar.

Ambas rutas exponen un endpoint compatible con OpenAI, por lo que Kodus puede comunicarse con ellas a través del proveedor **OpenAI-compatible**. Kodus también tiene un proveedor dedicado **Z.ai**, que se conecta mediante el endpoint compatible con Anthropic de Z.AI (`https://api.z.ai/api/anthropic`).

## Planes de un vistazo

> [!NOTE]
>
> Los precios y las cuotas cambian con regularidad. Siempre confirma los números actuales en [z.ai/subscribe](https://z.ai/subscribe) y [docs.z.ai](https://docs.z.ai/devpack/overview) antes de elegir un nivel.

### GLM Coding Plan (suscripción)

| Nivel | Precio (equivalente mensual) | Equivalente aproximado en valor de API | Concurrencia |
| - | - | - | - |
| **Lite** | \~\$18/mes (facturado trimestralmente) | \~15× la tarifa mensual | \~1 concurrente |
| **Pro** | \~\$30/mes (facturado trimestralmente) | \~20× la tarifa mensual | \~1 concurrente |
| **Max** | \~\$80/mes (facturado trimestralmente) | \~30× la tarifa mensual | hasta 30 concurrentes |

* Las cuotas se reinician en una ventana de **5 horas** continua y una ventana **semanal** — planifica en torno al techo, no a un tope mensual.
* La cobertura incluye GLM-5.1, GLM-5-Turbo, GLM-5, GLM-4.5 y GLM-4.5-Air.
* Endpoints del Coding Plan: `https://api.z.ai/api/anthropic` (compatible con Anthropic — el que usa el proveedor **Z.ai** en Kodus) y `https://api.z.ai/api/coding/paas/v4` (compatible con OpenAI). El endpoint estándar `/api/paas/v4/` no consume del Coding Plan.

### Developer API de pago por token

| Modelo | Precio (1M tokens de entrada / salida) | Ventana 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** | nivel inferior, optimizado para enrutamiento | \~128k tokens |

Endpoint estándar: `https://api.z.ai/api/paas/v4/` (compatible con OpenAI).

## Crear una clave de API

> [!WARNING]
>
> Se requiere una cuenta de Z.AI para crear una clave de API.

**Suscriptor del Coding Plan**

1. Inicia sesión en [z.ai](https://z.ai).
2. Adquiere un nivel del **GLM Coding Plan** en [z.ai/subscribe](https://z.ai/subscribe).
3. Abre la página de gestión de claves para tu suscripción y crea una clave del Coding Plan.
4. Copia la clave — no podrás verla nuevamente.

> [!NOTE]
>
> Las claves del Coding Plan están vinculadas a los endpoints del Coding Plan (`/api/anthropic` y `/api/coding/paas/v4`). **Devolverán 401** si se envían contra el endpoint estándar `/api/paas/v4/`.

**Developer API (pago por token)**

1. Inicia sesión en [z.ai](https://z.ai).
2. Abre la sección **API Keys** en [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).
3. Haz clic en **Create API Key**, dale un nombre descriptivo (por ejemplo, `kodus-prod`) y copia la clave.

> [!NOTE]
>
> Las claves del Developer API están vinculadas al endpoint `/api/paas/v4/`.

## Configurar Z.AI en Kodus

El flujo principal es la página **AI providers** en Kodus Cloud. Los usuarios con alojamiento autónomo que prefieren fijar el proveedor a nivel de proceso pueden usar variables de entorno en su lugar.

### Opción 1 — Proveedor Z.ai en Kodus Cloud (recomendado)

**1. Abrir AI providers y elegir Z.ai**

En la barra lateral, abre **AI providers** ([app.kodus.io/byok](https://app.kodus.io/byok)). En la pestaña **Providers**, haz clic en el mosaico **Z.ai** (en **Connect your first provider**, o en **Add another provider** si ya conectaste uno).

**2. Pegar tu clave de API e ingresar el modelo**

Pega tu clave de Z.AI en la tarjeta **API key** y luego escribe el ID del modelo (por ejemplo, `glm-5.1`) en **Model**. Kodus completa el endpoint `https://api.z.ai/api/anthropic` por ti — el endpoint compatible con Anthropic que Z.AI documenta para el GLM Coding Plan —, así que este mosaico no tiene selector de plan ni campo de URL base. Para usar un endpoint específico compatible con OpenAI, usa la Opción 2 más abajo.

**3. Definir la concurrencia (Coding Plan)**

Kodus no rellena previamente la concurrencia. En Coding Plan Lite/Pro, abre **Advanced (optional)** y define **Max concurrent requests** en `1`; súbelo hasta 30 si estás en Max.

**4. Probar y guardar**

Haz clic en **Test & save**. Kodus prueba la conexión y guarda la configuración si tiene éxito. 401 significa que la clave no coincide con el endpoint.

### Ajustar el razonamiento (opcional)

**Thinking / Reasoning** está en **Advanced (optional)**. Para GLM, cualquier nivel distinto de Off emite `thinking: { type: "enabled" }`, lo que está bien para la mayoría de las cargas. Dos casos para sobrescribir:

* **Forzar un presupuesto específico de tokens** — cambia **Thinking / Reasoning** a **Custom** y pega:

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

* **Deshabilitar el pensamiento** — para las revisiones más rápidas/económicas en PRs pequeños:

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

> [!NOTE]
>
> No necesitas envolver en namespace — Kodus envuelve las opciones bajo el namespace del provider activo antes de enviar. Consulta [main BYOK doc → Custom JSON override](https://docs.kodus.io/es/how_to_use/byok.md#sobrescritura-con-json-personalizado) para más detalles.

### Ajustar la concurrencia

* **Coding Plan Lite / Pro**: define **Max concurrent requests** en `1`. Subirlo devuelve `429 Too much concurrency`.
* **Coding Plan Max**: sube primero a `5`, hasta `30` si no ves errores 429. El nivel Max permite hasta 30 concurrentes.
* **Developer API**: empieza vacío (sin tope). Baja a `5` si ves errores de límite de tasa, luego ajusta hacia arriba.

> [!NOTE]
>
> En la pestaña **Routing**, define GLM 5.1 como **Model for all tasks** y un modelo de OpenAI o Anthropic como **Fallback (optional)** para que las revisiones sigan funcionando cuando tu ventana de 5 horas del Coding Plan se agote. Kodus conmuta automáticamente.

### Opción 2 — Endpoint compatible con OpenAI

Para conectarte mediante uno de los endpoints compatibles con OpenAI de Z.AI, abre **AI providers**, elige **OpenAI-compatible** en **Custom** en la pestaña **Providers** y completa:

| 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** | tu clave de Z.AI (coincidiendo con la URL base de arriba) |
| **Max concurrent requests** (en **Advanced (optional)**) | `1` en Lite/Pro del Coding Plan; hasta `30` en Max; déjalo vacío en Developer API |

### Opción 3 — Alojamiento autónomo (variables de entorno)

Si ejecutas Kodus en Modo Fijo (proveedor global único, sin BYOK por organización), configura Z.AI en el `.env` de tus contenedores de API + worker:

```env theme={null}
# Configuración de Z.AI (Modo Fijo)
API_LLM_PROVIDER_MODEL="glm-5.1"                                  # cualquier modelo GLM al que tengas acceso
API_OPENAI_FORCE_BASE_URL="https://api.z.ai/api/coding/paas/v4"   # usa /api/paas/v4/ para pago por token
API_OPEN_AI_API_KEY="your-z-ai-api-key"
```

> [!NOTE]
>
> Esta opción solo es necesaria para instalaciones de Kodus con alojamiento autónomo que deshabilitan deliberadamente el BYOK. Si el BYOK está habilitado en tu instancia con alojamiento autónomo, prefiere la **Opción 1** — la página **AI providers** funciona igual que en Cloud.

Reinicia los contenedores de API y worker después de editar `.env`, luego verifica la integración:

```bash theme={null}
docker-compose logs api worker | grep -iE "z\.ai|glm"
```

Para la configuración completa con alojamiento autónomo (dominios, claves de seguridad, base de datos, webhooks, proxy inverso), sigue la [guía de despliegue en VM genérica](https://docs.kodus.io/es/how_to_deploy/deploy_kodus/generic_vm.md) y solo reemplaza el bloque LLM con el anterior.

## Elegir entre el Coding Plan y el pago por token

* Elige el **Coding Plan** cuando tengas un equipo de revisores predecible y quieras un costo mensual fijo. Las cuotas de 5 horas y semanales se traducen en aproximadamente 15–30× la tarifa de suscripción en gasto equivalente de API.
* Elige el **pago por token** cuando tu tráfico sea irregular, cuando necesites acceso ocasional a las ventanas de contexto más grandes, o cuando quieras que el costo escale linealmente con el volumen de PRs.
* **Combínalos**: en **Routing**, usa el Coding Plan como **Model for all tasks** y una clave de Developer API (o un proveedor completamente diferente) como **Fallback (optional)** para cubrir ráfagas que agoten tu ventana de suscripción.

## Solución de problemas

> **401 después de Test — la clave no coincide con el endpoint**
>
> * Las claves del Coding Plan funcionan en `/api/anthropic` y `/api/coding/paas/v4`, no en `/api/paas/v4/`. Las claves del Developer API usan `/api/paas/v4/`.
> * El mosaico **Z.ai** siempre usa `https://api.z.ai/api/anthropic`. Si tu clave solo es válida en otro endpoint, conéctala mediante **OpenAI-compatible** con esa **Base URL**.
> * Con **OpenAI-compatible**, confirma que la **Base URL** coincida con el origen de la clave.

> **'Too much concurrency' durante la revisión**
>
> * Los niveles Lite y Pro del Coding Plan normalmente permiten solo **1 solicitud concurrente**. Define **Max concurrent requests** en `1`; súbelo solo en Max.
> * Baja **Max concurrent requests** en la configuración avanzada si sigues recibiendo errores 429.

> **Cuota agotada en el Coding Plan**
>
> * Las cuotas se aplican en una **ventana continua de 5 horas** y una **ventana semanal**. Alcanzar una de ellas devuelve HTTP 429.
> * Verifica la cuota restante en la consola de Z.AI.
> * Opciones: espera a la próxima ventana, actualiza a un nivel superior, o ten una clave de Developer API configurada como el modelo **Fallback (optional)** en **Routing** para cubrir la brecha.

> **Modelo no encontrado**
>
> * Verifica que el ID del modelo coincida con el catálogo de Z.AI (`glm-5.1`, `glm-5-turbo`, `glm-5`, `glm-4.5`, `glm-4.5-air`).
> * El Coding Plan actualmente cubre solo la familia GLM — los nombres de modelos que no sean GLM serán rechazados.

> **Errores de conexión (timeout, DNS)**
>
> * Confirma que tu servidor pueda alcanzar `api.z.ai`.
> * Revisa los registros de la API y del worker para ver el error upstream exacto.
> * Si estás en una región con tráfico saliente restringido, enruta las solicitudes a través de un proxy inverso que tu infraestructura permita.

## Relacionado

* [GLM Coding Plan (precios)](https://z.ai/subscribe)
* [Documentación para desarrolladores de Z.AI](https://docs.z.ai/devpack/overview)
* [Resumen de BYOK](https://docs.kodus.io/es/how_to_use/byok.md)


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