⚡ Zcode2API

OpenAI & Anthropic-compatible proxy for Z.AI (ZCode Start Plan) with JWT account pool, automatic failover, captcha solving, and smart proxy rotation.

Features • Quick Start • Usage • Configuration • API Endpoints • Contact

English | Русский

Features

• 🚀 Single Binary — server, captcha solver, and token pool in one executable
• 🔓 Dual Protocol — Anthropic Messages (/v1/messages) + OpenAI Chat (/v1/chat/completions)
• 🧩 Account Pool — JWT rotation with automatic failover on quota exhaustion
• 🛡️ Smart Failover — handles 429, load errors (3012/3007/3009/3010/529) with proxy rotation
• 📊 Live Dashboard — account quotas, proxy profiles, real-time monitoring
• 🌐 Proxy Support — sticky/rotate modes, auto-pause on failures, IP probing
• 🔐 Captcha Auto-Solve — embedded Node.js solver for Aliyun captchas
• 🎯 Dynamic Models — catalog synced from account billing (currently GLM-5.3 & GLM-5.3-Flash)
• 📦 Zero Dependencies — Node.js solver embedded, SQLite database, no external services

💡 Works with Cursor, OpenCode, Claude Code, and any OpenAI/Anthropic-compatible client out of the box!

Quick Start

1. Download

Download the latest release for your platform:

• Windows (64-bit)
• Linux (64-bit)
• macOS Intel
• macOS Apple Silicon

Or build from source:

git clone https://github.com/D3-vin/Zcode2Api.git
cd Zcode2Api
go build -trimpath -ldflags="-s -w" -o zcode2api ./cmd/zcode2api

Requirements:

• Node.js on PATH (for captcha solver)
• Go 1.25+ (if building from source)

2. Configure

cp .env.example .env
# Edit .env — change AUTH_TOKEN to your own secret

3. Run

./zcode2api

Dashboard: http://localhost:3101

4. Add Accounts

Option 1: Dashboard Login (Recommended)

1. Open http://localhost:3101 → login with your AUTH_TOKEN
2. Click Login Z.AI → authorize via OAuth
3. JWT auto-added to pool with quota refresh

Option 2: Bulk Import

1. Dashboard → Add (bulk) → paste JWT tokens (one per line)

Option 3: File Import

1. Create tokens.txt with JWT tokens (one per line)
2. Set ZCODE_KEYS=tokens.txt in .env
3. Restart server

5. Test

OpenAI format:

curl -N http://localhost:3101/v1/chat/completions \
  -H "Authorization: Bearer d3vin" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.3",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Anthropic format:

curl -N http://localhost:3101/v1/messages \
  -H "x-api-key: d3vin" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.3",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 1024,
    "stream": true
  }'

Usage

IDE Configuration

For OpenAI-compatible clients (Cursor, OpenCode, etc.):

Base URL: http://localhost:3101/v1
API Key: d3vin  # your AUTH_TOKEN
Model: GLM-5.3

For Anthropic-compatible clients (Claude Code):

Base URL: http://localhost:3101
API Key: d3vin  # your AUTH_TOKEN
Model: GLM-5.3

Dashboard Features

Accounts Tab:

• Add accounts via OAuth, bulk JWT paste, or file import
• View quotas, status (Active/Standby/Cooling/Exhausted/Revoked/Disabled)
• Manual quota refresh or auto-refresh (configurable interval)
• Claim available plans with preview
• Export/import pool with device identities (JSON)

Proxies Tab:

• Add proxy profiles (sticky/rotate mode)
• Assign proxies to specific accounts (sticky egress)
• Auto-pause after 2 probe failures
• IP probing with configurable delay

Settings:

• Change AUTH_TOKEN and GATEWAY_KEY on-the-fly (persists to DB)
• Configure billing workers, failover limits, captcha timeouts

API Endpoints

Authorization:

• Header: Authorization: Bearer <token> or x-api-key: <token>
• Token: AUTH_TOKEN (dashboard + /api/*) or GATEWAY_KEY (if set, for /v1/* and /async)

Configuration

All settings in .env (see .env.example for full reference):

Dynamic Settings:

• AUTH_TOKEN and GATEWAY_KEY can be changed in Dashboard → Settings (persists to DB, survives restarts)

Error Handling

Account Statuses:

• Active — ready for requests
• Standby — available but not currently selected
• Cooling — 3 strikes → 30-minute cooldown
• Exhausted — quota depleted, waiting for reset
• Revoked — 401 error, invalid JWT
• Expired — JWT expired
• Disabled — manually toggled off (survives quota refresh)

Proxies

Supported Formats:

http://proxy.example.com:8080
http://user:[email protected]:8080
https://proxy.example.com:443
socks5://proxy.example.com:1080
socks5://user:[email protected]:1080

Behavior:

• Chat and billing requests use one egress per account (sticky)
• Captcha minting always goes direct from server machine
• Empty proxy pool = direct connection

Proxy Profiles:

• Sticky mode — assign specific proxy to account (egress locked)
• Rotate mode — proxy rotates on each request
• Auto-pause — disables proxy after 2 consecutive probe failures
• IP Probe — periodic IP check with configurable delay

Troubleshooting

Project Structure

Zcode2Api/
├── zcode2api                    # Binary (Linux/macOS)
├── zcode2api.exe                # Binary (Windows)
├── .env                         # Configuration (copy from .env.example)
├── .env.example                 # Configuration template
├── proxy.txt                    # Proxy seed file (optional)
├── tokens.txt                   # JWT seed file (optional)
├── data/                        # Runtime data directory
│   ├── zcode2api.db            # SQLite database (accounts, proxies, settings)
│   └── captcha_node/           # Embedded captcha solver (auto-extracted)
├── cmd/zcode2api/               # Main application
├── internal/
│   ├── gateway/                 # Core server logic
│   ├── captcha/                 # Captcha solver integration
│   ├── store/                   # Database layer
│   ├── upstream/                # Z.AI client
│   ├── proxy/                   # Proxy management
│   └── config/                  # Configuration loader
└── tests/                       # Test suite

Building

Cross-platform builds:

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o build/zcode2api-windows-amd64.exe ./cmd/zcode2api

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o build/zcode2api-linux-amd64 ./cmd/zcode2api

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o build/zcode2api-macos-amd64 ./cmd/zcode2api

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o build/zcode2api-macos-arm64 ./cmd/zcode2api

Custom version:

go build -ldflags "-X main.AppVersion=1.0.1" -o zcode2api ./cmd/zcode2api

Contact

• GitHub: https://github.com/D3-vin/Zcode2Api
• Telegram: @D3_vin
• Author: @D3vin_dev

License

Provided AS-IS without warranty. Use at your own risk.

⚠️ Disclaimer: This tool is for educational purposes. Ensure compliance with Z.AI Terms of Service.