Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add the Z.ai pay-as-you-go API provider (#1426)

Ali Khokhar6ea47a3e823f
diff --git a/.env.example b/.env.example
index 65fb034f..e0ea920e 100644
--- a/.env.example
+++ b/.env.example
@@ -64,7 +64,8 @@ BEDROCK_BASE_URL="https://bedrock-mantle.us-east-1.api.aws/v1"
# GITHUB_MODELS_TOKEN=<your-token>
-# Z.ai Config (GLM Coding Plan OpenAI-compatible Chat Completions at api.z.ai/api/coding/paas/v4)
+# Z.ai Config (one key for Coding Plan zai/... and pay-as-you-go zai_api/...)
+# The model prefix selects api.z.ai/api/coding/paas/v4 or api.z.ai/api/paas/v4.
# ZAI_API_KEY=<your-token>
@@ -216,6 +217,7 @@ MODEL="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
# FCC_SMOKE_MODEL_COHERE=<provider/model-id>
# FCC_SMOKE_MODEL_GITHUB_MODELS=<provider/model-id>
# FCC_SMOKE_MODEL_ZAI=<provider/model-id>
+# FCC_SMOKE_MODEL_ZAI_API=<provider/model-id>
# FCC_SMOKE_MODEL_TOKENROUTER=<your-token>
# FCC_SMOKE_MODEL_NARAROUTE=<provider/model-id>
# FCC_SMOKE_MODEL_FIREWORKS=<provider/model-id>
@@ -289,6 +291,7 @@ REASONING_HAIKU=inherit
# COHERE_PROXY=<http-or-socks-url>
# GITHUB_MODELS_PROXY=<http-or-socks-url>
# ZAI_PROXY=<http-or-socks-url>
+# ZAI_API_PROXY=<http-or-socks-url>
# TOKENROUTER_PROXY=<http-or-socks-url>
# NARAROUTE_PROXY=<http-or-socks-url>
# FIREWORKS_PROXY=<http-or-socks-url>
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 78aff29a..ed6f63dd 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -771,7 +771,7 @@ Responses-only models from Chat Completions discovery while keeping direct model
execution upstream-authoritative. Amazon Bedrock Mantle uses an ordinary profile with a region-specific,
configurable OpenAI base URL and bearer API key; AWS SigV4 and native
Converse/Invoke transports are outside that provider contract. Wafer, Kimi API,
-Kimi Code, MiniMax, Fireworks, and Z.ai use ordinary
+Kimi Code, MiniMax, Fireworks, and both Z.ai surfaces use ordinary
declarative profiles for their thinking, token, and `extra_body` policy. Kimi
Code remains distinct from Kimi API because its subscription key and base URL
are a separate customer contract; its profile maps provider-neutral reasoning
@@ -781,8 +781,12 @@ because its subscription key, quota, endpoint, and personal interactive-use
contract are separate. It uses the ordinary OpenAI Chat transport, preserves
reasoning history through `reasoning_content`, and does not impose one reasoning
control or output-token default across its heterogeneous model catalog.
-Z.ai is treated as the GLM Coding Plan provider and uses Z.ai's Coding Plan
-OpenAI base.
+Z.ai Coding Plan (`zai`) and Z.ai API (`zai_api`) are distinct provider
+identities because their fixed endpoints select Coding Plan quota versus
+pay-as-you-go balance. They share the upstream `ZAI_API_KEY` and one declarative
+wire policy, while retaining separate proxies, provider instances, admission
+state, learned output caps, model caches, status rows, and model prefixes. FCC
+never probes or falls back between the two billing endpoints.
Mistral La Plateforme keeps its native `reasoning_effort` and thinking-chunk
request/stream mapping inside
[providers/mistral/reasoning.py](src/free_claude_code/providers/mistral/reasoning.py), including its
diff --git a/README.md b/README.md
index 780d1c32..436973e1 100644
--- a/README.md
+++ b/README.md
@@ -195,7 +195,8 @@ fcc-codex exec "hello"
| [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` |
| [Novita AI](https://novita.ai/settings/key-management) | `NOVITA_API_KEY` | `novita/deepseek/deepseek-v4-flash-0731` |
| [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` | `cloudflare/@cf/moonshotai/kimi-k2.6` |
-| [Z.ai](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` |
+| [Z.ai Coding Plan](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` |
+| [Z.ai API (pay as you go)](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai_api/glm-4.7-flash` |
| [TokenRouter](https://www.tokenrouter.com/) | `TOKENROUTER_API_KEY` | `tokenrouter/moonshotai/kimi-k3-free` |
| [NaraRoute](https://router.bynara.id/) | `NARAROUTE_API_KEY` | `nararoute/kimi-k3-free` |
| [Ollama Cloud](https://ollama.com/settings/keys) | `OLLAMA_API_KEY` | `ollama_cloud/qwen3-coder:480b` |
diff --git a/pyproject.toml b/pyproject.toml
index c8f47271..22619df5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.2.0"
+version = "5.3.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 94a6eb1b..a2467aa5 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -68,6 +68,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"cohere": "cohere/command-a-plus-05-2026",
"github_models": "github_models/openai/gpt-4.1",
"zai": "zai/glm-5.2",
+ "zai_api": "zai_api/glm-4.7-flash",
"gemini": "gemini/models/gemini-3.1-flash-lite",
"vertex": "vertex/google/gemini-3.5-flash",
"groq": "groq/llama-3.3-70b-versatile",
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index d9151001..1f377cc3 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -86,7 +86,11 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
},
"ZAI_API_KEY": {
"label": "Z.ai API Key",
- "description": "Z.ai Coding Plan API key.",
+ "description": (
+ "Shared Z.ai key for Coding Plan (zai/...) and the general API "
+ "(zai_api/...). The selected model prefix chooses Coding Plan quota "
+ "or pay-as-you-go balance."
+ ),
},
"FIREWORKS_API_KEY": {
"label": "Fireworks API Key",
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index 844ee8eb..372e60de 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -38,8 +38,9 @@ BEDROCK_DEFAULT_BASE = "https://bedrock-mantle.us-east-1.api.aws/v1"
HUGGINGFACE_DEFAULT_BASE = "https://router.huggingface.co/v1"
COHERE_DEFAULT_BASE = "https://api.cohere.ai/compatibility/v1"
GITHUB_MODELS_DEFAULT_BASE = "https://models.github.ai/inference"
-# Z.ai GLM Coding Plan OpenAI-compatible Chat Completions API.
-ZAI_DEFAULT_BASE = "https://api.z.ai/api/coding/paas/v4"
+# Z.ai OpenAI-compatible Chat Completions APIs. The endpoint selects billing.
+ZAI_CODING_DEFAULT_BASE = "https://api.z.ai/api/coding/paas/v4"
+ZAI_API_DEFAULT_BASE = "https://api.z.ai/api/paas/v4"
# Google AI Studio Gemini API OpenAI-compat layer (not Vertex AI).
GEMINI_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta/openai/"
# Vertex AI API root. The provider owns project/location endpoint composition.
@@ -479,12 +480,22 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
),
"zai": ProviderDescriptor(
provider_id="zai",
- display_name="Z.ai",
+ display_name="Z.ai Coding Plan",
credential_env="ZAI_API_KEY",
+ credential_url="https://z.ai/manage-apikey/apikey-list",
credential_attr="zai_api_key",
- default_base_url=ZAI_DEFAULT_BASE,
+ default_base_url=ZAI_CODING_DEFAULT_BASE,
proxy_attr="zai_proxy",
),
+ "zai_api": ProviderDescriptor(
+ provider_id="zai_api",
+ display_name="Z.ai API",
+ credential_env="ZAI_API_KEY",
+ credential_url="https://z.ai/manage-apikey/apikey-list",
+ credential_attr="zai_api_key",
+ default_base_url=ZAI_API_DEFAULT_BASE,
+ proxy_attr="zai_api_proxy",
+ ),
"tokenrouter": ProviderDescriptor(
provider_id="tokenrouter",
display_name="TokenRouter",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index 8b32e832..e24596e7 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -141,7 +141,7 @@ class Settings(BaseModel):
default=None, validation_alias="KILO_API_KEY"
)
- # ==================== Z.ai Config ====================
+ # ==================== Z.ai Coding Plan / General API ====================
zai_api_key: OptionalNonEmptyString = Field(
default=None, validation_alias="ZAI_API_KEY"
)
@@ -432,6 +432,9 @@ class Settings(BaseModel):
zai_proxy: OptionalNonEmptyString = Field(
default=None, validation_alias="ZAI_PROXY"
)
+ zai_api_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ZAI_API_PROXY"
+ )
tokenrouter_proxy: OptionalNonEmptyString = Field(
default=None, validation_alias="TOKENROUTER_PROXY"
)
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 244bef59..2ca67bc9 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -192,6 +192,24 @@ def _policy(
)
+def _zai_profile(provider_name: str) -> OpenAIChatProfile:
+ return OpenAIChatProfile(
+ _policy(
+ provider_name,
+ ReasoningReplayMode.REASONING_CONTENT,
+ reject_extra_body_message=(
+ "Z.ai Chat Completions API does not support caller extra_body on "
+ "requests."
+ ),
+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+ ),
+ ThinkingObjectReasoning(
+ enabled={"type": "enabled", "clear_thinking": False},
+ disabled={"type": "disabled"},
+ ),
+ )
+
+
OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
"xai": OpenAIChatProfile(
_policy(
@@ -569,20 +587,8 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
use_extra_body=True,
),
),
- "zai": OpenAIChatProfile(
- _policy(
- "ZAI",
- ReasoningReplayMode.REASONING_CONTENT,
- reject_extra_body_message=(
- "Z.ai Chat Completions API does not support caller extra_body on requests."
- ),
- default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
- ),
- ThinkingObjectReasoning(
- enabled={"type": "enabled", "clear_thinking": False},
- disabled={"type": "disabled"},
- ),
- ),
+ "zai": _zai_profile("ZAI"),
+ "zai_api": _zai_profile("ZAI_API"),
"nararoute": OpenAIChatProfile(
_policy(
"NARAROUTE",
diff --git a/tests/contracts/test_admin_provider_manifest.py b/tests/contracts/test_admin_provider_manifest.py
index 4cf220b8..34585c9b 100644
--- a/tests/contracts/test_admin_provider_manifest.py
+++ b/tests/contracts/test_admin_provider_manifest.py
@@ -1,6 +1,6 @@
"""Ensure admin UI manifest exposes every catalog credential/proxy binding."""
-from free_claude_code.config.admin.manifest import FIELD_BY_KEY
+from free_claude_code.config.admin.manifest import FIELD_BY_KEY, FIELDS
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
ProviderAuthKind,
@@ -149,6 +149,28 @@ def test_qwencloud_coding_key_is_a_distinct_admin_provider_field() -> None:
assert "separate endpoints" in entry.description
+def test_zai_shared_key_configures_both_distinct_provider_surfaces() -> None:
+ from free_claude_code.config.admin.status import provider_config_status
+
+ entry = FIELD_BY_KEY["ZAI_API_KEY"]
+ statuses = {
+ status["provider_id"]: status
+ for status in provider_config_status(
+ {"ZAI_API_KEY": {"value": "shared-zai-key"}}
+ )
+ }
+
+ assert sum(field.key == "ZAI_API_KEY" for field in FIELDS) == 1
+ assert entry.settings_attr == "zai_api_key"
+ assert "Coding Plan" in entry.description
+ assert "pay-as-you-go" in entry.description
+ assert statuses["zai"]["display_name"] == "Z.ai Coding Plan"
+ assert statuses["zai"]["status"] == "configured"
+ assert statuses["zai_api"]["display_name"] == "Z.ai API"
+ assert statuses["zai_api"]["status"] == "configured"
+ assert FIELD_BY_KEY["ZAI_API_PROXY"].settings_attr == "zai_api_proxy"
+
+
def test_vertex_admin_status_uses_project_configuration_not_an_api_key() -> None:
from free_claude_code.config.admin.status import provider_config_status
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 639f549b..fc783a19 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -46,6 +46,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"novita",
"cloudflare",
"zai",
+ "zai_api",
"tokenrouter",
"nararoute",
"ollama_cloud",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 1c2ebc91..12f40145 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -178,6 +178,44 @@ def test_xai_provider_smoke_uses_current_grok_model(monkeypatch) -> None:
assert models[0].source == "provider_default"
+def test_zai_shared_key_enables_both_provider_smoke_surfaces(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ZAI", raising=False)
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ZAI_API", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ zai_api_key="shared-zai-key",
+ )
+ )
+
+ models = config.provider_smoke_models()
+
+ assert [(model.provider, model.full_model, model.source) for model in models] == [
+ ("zai", "zai/glm-5.2", "provider_default"),
+ ("zai_api", "zai_api/glm-4.7-flash", "provider_default"),
+ ]
+
+
+def test_zai_api_smoke_override_is_independent_from_coding_plan(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ZAI", raising=False)
+ monkeypatch.setenv("FCC_SMOKE_MODEL_ZAI_API", "zai_api/glm-5.2")
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ zai_api_key="shared-zai-key",
+ )
+ )
+
+ models = config.provider_smoke_models()
+
+ assert [(model.provider, model.full_model, model.source) for model in models] == [
+ ("zai", "zai/glm-5.2", "provider_default"),
+ ("zai_api", "zai_api/glm-5.2", "FCC_SMOKE_MODEL_ZAI_API"),
+ ]
+
+
def test_qwencloud_provider_smoke_uses_current_coding_model(monkeypatch) -> None:
monkeypatch.delenv("FCC_SMOKE_MODEL_QWENCLOUD", raising=False)
config = _smoke_config(
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index f7ac5343..9d3f1ea5 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -34,7 +34,8 @@ from free_claude_code.config.provider_catalog import (
VERCEL_AI_GATEWAY_DEFAULT_BASE,
WANDB_INFERENCE_DEFAULT_BASE,
XAI_DEFAULT_BASE,
- ZAI_DEFAULT_BASE,
+ ZAI_API_DEFAULT_BASE,
+ ZAI_CODING_DEFAULT_BASE,
ZENMUX_DEFAULT_BASE,
)
from free_claude_code.providers.admission import ProviderAdmissionController
@@ -125,6 +126,7 @@ def _make_settings(**overrides):
mock.cohere_proxy = None
mock.github_models_proxy = None
mock.zai_proxy = None
+ mock.zai_api_proxy = None
mock.tokenrouter_proxy = None
mock.nararoute_proxy = None
mock.agnes_proxy = None
@@ -548,10 +550,11 @@ def test_local_provider_factory_resolves_catalog_static_credential(
assert provider._api_key == expected_api_key
-def test_zai_descriptor_uses_fixed_cloud_base_url():
+def test_zai_coding_descriptor_uses_fixed_cloud_base_url():
descriptor = PROVIDER_CATALOG["zai"]
- assert descriptor.default_base_url == ZAI_DEFAULT_BASE
+ assert descriptor.display_name == "Z.ai Coding Plan"
+ assert descriptor.default_base_url == ZAI_CODING_DEFAULT_BASE
assert descriptor.base_url_attr is None
@@ -563,7 +566,31 @@ def test_zai_provider_config_ignores_stale_base_url_setting():
_make_settings(zai_base_url="https://custom.zai.invalid/v1"),
)
- assert config.base_url == ZAI_DEFAULT_BASE
+ assert config.base_url == ZAI_CODING_DEFAULT_BASE
+
+
+def test_zai_api_provider_config_uses_shared_key_general_base_and_own_proxy():
+ descriptor = PROVIDER_CATALOG["zai_api"]
+ settings = _make_settings(
+ zai_api_key="shared-zai-key",
+ zai_api_proxy="http://proxy.test:8080",
+ )
+
+ config = build_provider_config(descriptor, settings)
+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
+ provider = create_provider("zai_api", settings)
+
+ assert descriptor.display_name == "Z.ai API"
+ assert descriptor.credential_env == "ZAI_API_KEY"
+ assert descriptor.credential_attr == "zai_api_key"
+ assert descriptor.default_base_url == ZAI_API_DEFAULT_BASE
+ assert descriptor.base_url_attr is None
+ assert descriptor.proxy_attr == "zai_api_proxy"
+ assert config.api_key == "shared-zai-key"
+ assert config.base_url == ZAI_API_DEFAULT_BASE
+ assert config.proxy == "http://proxy.test:8080"
+ assert isinstance(provider, OpenAIChatProvider)
+ assert provider._provider_name == "ZAI_API"
def test_minimax_descriptor_uses_expected_endpoint_and_credential():
@@ -795,6 +822,7 @@ def test_create_provider_instantiates_each_builtin():
"cohere": OpenAIChatProvider,
"github_models": GitHubModelsProvider,
"zai": OpenAIChatProvider,
+ "zai_api": OpenAIChatProvider,
"tokenrouter": OpenAIChatProvider,
"nararoute": OpenAIChatProvider,
"agnes": OpenAIChatProvider,
diff --git a/tests/providers/test_zai.py b/tests/providers/test_zai.py
index bd6fb172..8cc4d0ea 100644
--- a/tests/providers/test_zai.py
+++ b/tests/providers/test_zai.py
@@ -1,4 +1,4 @@
-"""Tests for the Z.ai OpenAI-chat Coding Plan provider."""
+"""Tests for the Z.ai OpenAI-chat provider surfaces."""
from unittest.mock import AsyncMock, MagicMock
@@ -6,7 +6,10 @@ import pytest
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
-from free_claude_code.config.provider_catalog import ZAI_DEFAULT_BASE
+from free_claude_code.config.provider_catalog import (
+ ZAI_API_DEFAULT_BASE,
+ ZAI_CODING_DEFAULT_BASE,
+)
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
@@ -16,14 +19,20 @@ from tests.providers.support import (
reasoning_for,
)
+_ZAI_BASES = {
+ "zai": ZAI_CODING_DEFAULT_BASE,
+ "zai_api": ZAI_API_DEFAULT_BASE,
+}
+
-def zai_provider():
[email protected](params=tuple(_ZAI_BASES))
+def zai_provider(request: pytest.FixtureRequest):
+ provider_id = request.param
return profiled_provider(
- "zai",
+ provider_id,
make_provider_config(
api_key="test_zai_key",
- base_url=ZAI_DEFAULT_BASE,
+ base_url=_ZAI_BASES[provider_id],
rate_limit=10,
rate_window=60,
),
@@ -31,10 +40,14 @@ def zai_provider():
)
-def test_init_uses_openai_chat_coding_endpoint(zai_provider):
+def test_init_uses_surface_specific_openai_chat_endpoint(zai_provider):
assert isinstance(zai_provider, OpenAIChatProvider)
assert zai_provider._api_key == "test_zai_key"
- assert zai_provider._base_url == "https://api.z.ai/api/coding/paas/v4"
+ expected_base = {
+ "ZAI": ZAI_CODING_DEFAULT_BASE,
+ "ZAI_API": ZAI_API_DEFAULT_BASE,
+ }[zai_provider._provider_name]
+ assert zai_provider._base_url == expected_base
def test_build_request_body_openai_chat(zai_provider):
diff --git a/uv.lock b/uv.lock
index effab848..1ef36fd4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.2.0"
+version = "5.3.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },