zai-setup

z.ai (Zhipu AI) Setup Guide

z.ai (formerly Zhipu AI / 智谱AI, rebranded July 2025) is a Chinese AI company that develops the GLM (General Language Model) family. They provide both OpenAI-compatible and Anthropic-compatible API endpoints.

• Platform: https://z.ai/ (international) / https://open.bigmodel.cn/ (China)
• Docs: https://docs.z.ai/
• API Base URL (International): https://api.z.ai/api/paas/v4/
• API Base URL (China): https://open.bigmodel.cn/api/paas/v4/
• Anthropic-compatible endpoint: https://api.z.ai/api/anthropic
• Pricing: https://docs.z.ai/guides/overview/pricing

Getting an API Key

1. Visit https://z.ai/model-api (international) or https://open.bigmodel.cn/ (China)
2. Create an account (email or phone verification required)
3. Navigate to API Keys in your account dashboard
4. Generate and copy your API key

API Compatibility

z.ai provides two compatible API formats:

OpenAI-Compatible API

curl "https://api.z.ai/api/paas/v4/chat/completions" \
  -H "Authorization: Bearer YOUR_ZHIPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ZHIPU_API_KEY",
    base_url="https://api.z.ai/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-4.7",
    messages=[{"role": "user", "content": "Hello!"}]
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_ZHIPU_API_KEY",
  baseURL: "https://api.z.ai/api/paas/v4/",
});

const response = await client.chat.completions.create({
  model: "glm-4.7",
  messages: [{ role: "user", content: "Hello!" }],
});

Anthropic-Compatible API

z.ai also provides an endpoint that speaks the Anthropic Messages API protocol. This is what enables direct Claude Code integration.

Using z.ai with Claude Code

Option 1: Direct via Anthropic-Compatible Endpoint (Recommended)

z.ai provides a native Anthropic-compatible endpoint at https://api.z.ai/api/anthropic. Claude Code can connect directly — no proxy needed.

In ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Or via shell alias:

# Add to ~/.bashrc or ~/.zshrc
zaiclaude() {
  ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
  ANTHROPIC_AUTH_TOKEN="your-zai-api-key" \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude "$@"
}

Optional model mapping — map Claude Code's model slots to specific GLM models:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Variable	Purpose
ANTHROPIC_BASE_URL	Points Claude Code to z.ai's Anthropic endpoint
ANTHROPIC_AUTH_TOKEN	Your z.ai API key
ANTHROPIC_API_KEY	Set to "" to avoid conflicts with existing Anthropic key
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Prevents background traffic to Anthropic servers
ANTHROPIC_DEFAULT_SONNET_MODEL	GLM model for the "Sonnet" slot
ANTHROPIC_DEFAULT_OPUS_MODEL	GLM model for the "Opus" slot
ANTHROPIC_DEFAULT_HAIKU_MODEL	GLM model for the "Haiku" slot

Note: See https://docs.z.ai/scenario-example/develop-tools/claude for z.ai's official Claude Code integration guide.

Option 2: Via Cloudflare AI Gateway

Route z.ai through Cloudflare AI Gateway for logging, caching, and cost tracking. See the cloudflare-ai-gateway skill for full setup.

# Use the universal endpoint to proxy z.ai through your gateway
curl "https://gateway.ai.cloudflare.com/v1/ACCT_ID/GATEWAY_ID" \
  -H "Content-Type: application/json" \
  -d '[{
    "provider": "zhipu",
    "endpoint": "https://api.z.ai/api/paas/v4/chat/completions",
    "headers": { "Authorization": "Bearer YOUR_ZHIPU_API_KEY" },
    "query": {
      "model": "glm-4.7",
      "messages": [{"role": "user", "content": "Hello"}]
    }
  }]'

Option 3: Via OpenRouter

OpenRouter aggregates many model providers including z.ai/Zhipu models:

curl "https://openrouter.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zhipu/glm-4.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Claude Code Web Sessions

For Claude Code web sessions, set environment variables in .claude/settings.local.json (gitignored):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Important: Never put API keys in settings.json (committed). Always use settings.local.json (gitignored) or a secrets manager like 1Password. These use the same Anthropic-compatible environment variables as Option 1 above.

Coding Plan

z.ai offers a Coding Plan subscription for enhanced coding model access:

• Lite: $10/mo
• Pro: $30/mo
• Endpoint: https://api.z.ai/api/coding/paas/v4

References

• z.ai Platform
• z.ai Developer Docs
• z.ai Pricing
• Claude Code Integration Guide
• OpenRouter Zhipu Models
• Cloudflare AI Gateway Universal Endpoint
• z.ai on GitHub
• z.ai on Hugging Face