README.md

metadata

title: Z.ai API
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860

z-ai2api_python

GLM proxy service based on FastAPI + Granian Suitable for local development, self-hosted proxy, Token pool management, and compatible client access

English / 中文简体

🚀 Hugging Face Setup Guide

1. Admin Panel Configuration

After your Space is running:

1. Go to https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/admin.
2. Login with password (default: admin123).
3. Change Password: Go to "Settings" in Hugging Face and add an Environment Variable ADMIN_PASSWORD.
4. Add Tokens: Go to the Tokens tab to add your GLM tokens to the pool.

2. Claude Code Setup

To use this Space with Claude Code, run:

export CLAUDE_CONFIG_BASE_URL="https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/anthropic"
export ANTHROPIC_API_KEY="your_auth_token"
claude

Note: your_auth_token should match the AUTH_TOKEN environment variable in your Space (default is empty/none if not set).

3. OpenClaude / OpenAI Client Setup

For any OpenAI-compatible client:

• Base URL: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/v1
• API Key: Your AUTH_TOKEN
• Model: GLM-4.5 or GLM-5

---

Features

• Compatible with OpenAI, Claude Code, Anthropic style requests
• Supports streaming responses, tool calls, Thinking models
• Built-in Token pool, supports polling, failure circuit breaker, recovery, and health checks
• Provides admin panel: Dashboard, Token management, Configuration management, Real-time logs
• Uses SQLite to store Tokens and request logs, simple deployment
• Supports local running and Docker / Docker Compose deployment

Quick Start

Environment Requirements

• Python 3.9 to 3.12
• Recommend using uv

Local Startup

git clone https://github.com/ZyphrZero/z.ai2api_python.git
cd z.ai2api_python

uv sync
cp .env.example .env
uv run python main.py

First startup will automatically initialize the database.

Default addresses:

• API root path: http://127.0.0.1:8080
• OpenAI docs: http://127.0.0.1:8080/docs
• Admin panel: http://127.0.0.1:8080/admin

Docker Compose

docker compose -f deploy/docker-compose.yml up -d --build

More deployment instructions see deploy/README_DOCKER.md.

Minimum Configuration

At least suggest confirming these environment variables:

Variable	Description
AUTH_TOKEN	Bearer Token used by clients to access this service
ADMIN_PASSWORD	Admin panel login password, default value must be changed
LISTEN_PORT	Service listening port, default 8080
ANONYMOUS_MODE	Whether to enable anonymous mode
GUEST_POOL_SIZE	Anonymous pool capacity
DB_PATH	SQLite database path
TOKEN_FAILURE_THRESHOLD	Token consecutive failure threshold
TOKEN_RECOVERY_TIMEOUT	Token recovery wait time

Complete configuration please see .env.example.

Admin Panel

Admin panel unified entry:

• /admin: Dashboard
• /admin/tokens: Token management
• /admin/config: Configuration management
• /admin/logs: Real-time logs

Common Commands

# Start service
uv run python main.py

# Run tests
uv run pytest

# Run an existing smoke test
uv run python tests/test_simple_signature.py

# Lint
uv run ruff check app tests main.py

Compatible Interfaces

Common interface entries:

• OpenAI compatible: /v1/chat/completions
• Anthropic compatible: /v1/messages
• Claude Code compatible: /anthropic/v1/messages

Model mapping and default model can be adjusted in .env or admin configuration page.

⭐ Star History

License

This project uses MIT license - see LICENSE file for details.

Disclaimer

• This project is for learning and research use only, do not use for other purposes
• This project is not affiliated with Z.AI official
• Please ensure compliance with Z.AI's terms of service before use
• Do not use for commercial purposes or scenarios that violate terms of service
• Users must bear their own usage risks

---

Made with ❤️ by the community