README
¶
Z.AI API Client
English | 简体中文
A Go CLI and client library for the Z.AI (Zhipu AI) API platform: chat
completions, models, images, video, audio, embeddings, moderation, rerank,
agents, batch jobs, file parsing, GLM Coding Plan account/quota management,
and a Go port of @z_ai/coding-helper for wiring Claude Code, OpenCode,
Crush, Factory Droid, and Cursor to your GLM Coding Plan.
Install
go install github.com/SamyRai/go-z-ai@latest
Requires Go 1.26.4+ and a Z.AI API key. Building from source, first-run auth, and troubleshooting: Getting Started →
Quick example
export ZAI_API_KEY=your_api_key_here
zai-client chat create "Explain goroutines in one paragraph" --stream
import "github.com/SamyRai/go-z-ai/pkg/client"
c, _ := client.NewClientFromEnv()
resp, _ := c.Chat().Create(ctx, client.ChatRequest{
Model: "glm-5.2",
Messages: []client.Message{{Role: "user", Content: "Explain goroutines in one paragraph"}},
})
fmt.Println(resp.Choices[0].Message.Content)
More runnable programs — streaming, async image polling, the Anthropic
/v1/messages endpoint — live under examples/.
Documentation
| Getting Started | CLI Reference |
| Accounts & Quota | Coding Tools |
| Library Guide | Error Handling |
| Architecture | Roadmap & Known Limitations |
| Contributing | Security Policy |
| Code of Conduct | Changelog |
What's covered
Chat (streaming, structured output, deep thinking, function calling, vision),
the Anthropic-compatible /v1/messages endpoint, Models, Images, Video, Audio
(transcription + TTS + voice cloning), OCR & document parsing, Embeddings,
Moderations, Rerank, Agents, Files, Batch jobs, GLM Coding Plan
usage/quota/multi-account management, and a full-screen terminal UI
(zai-client tui). See CLI Reference for the complete
command list or Library Guide for the Go API.
How it relates to the official SDKs
Z.AI / Zhipu publish official SDKs for Python
(zai-org/z-ai-sdk-python, PyPI
zai-sdk), Node (MetaGLM/zhipuai-sdk-nodejs-v4),
and Java (MetaGLM/zhipuai-sdk-java-v4).
There is no official Go SDK — go-z-ai fills that gap, and layers a CLI,
a TUI, regional gateway switching (api.z.ai ↔ open.bigmodel.cn), and GLM
Coding Plan multi-account management on top of the same API surface.
ℹ️
zai-claude-config.jsonat the repo root is a template with placeholder values ("your-zai-api-key-here") used byzai-client coding load claude-code. It is not a real config and ships no credentials.
Contributing
See CONTRIBUTING.md — in particular, this project's live-verification convention (recorded API cassettes instead of hand-wished fixtures) if you're adding or changing a service.
License
Apache License 2.0 — see LICENSE.
Support
- Z.AI API docs: https://docs.z.ai
- Issues: GitHub Issues
- Security: see SECURITY.md — please don't file vulnerabilities as public issues
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
anthropic-messages
command
Command anthropic-messages hits the Anthropic-compatible /v1/messages endpoint exposed by Z.AI, using the same API key (Bearer auth, not x-api-key).
|
Command anthropic-messages hits the Anthropic-compatible /v1/messages endpoint exposed by Z.AI, using the same API key (Bearer auth, not x-api-key). |
|
async-poll
command
Command async-poll demonstrates the async image flow: submit a request, receive a task id, then block on WaitForResult until the task is terminal.
|
Command async-poll demonstrates the async image flow: submit a request, receive a task id, then block on WaitForResult until the task is terminal. |
|
chat-streaming
command
Command chat-streaming is a minimal example of streaming a chat completion token-by-token with the Z.AI Go client.
|
Command chat-streaming is a minimal example of streaming a chat completion token-by-token with the Z.AI Go client. |
|
internal
|
|
|
accounts
Package accounts persists multiple named Z.AI credentials and tracks which one is active, so the CLI can switch between accounts without hand-editing .env.
|
Package accounts persists multiple named Z.AI credentials and tracks which one is active, so the CLI can switch between accounts without hand-editing .env. |
|
coding
Package coding is a Go port of Z.AI's official @z_ai/coding-helper ("chelper") CLI.
|
Package coding is a Go port of Z.AI's official @z_ai/coding-helper ("chelper") CLI. |
|
fileinput
Package fileinput resolves a user-supplied "file or URL" argument into the value the layout/OCR API expects: an http(s) URL is passed through verbatim, while a local path is read and base64-encoded.
|
Package fileinput resolves a user-supplied "file or URL" argument into the value the layout/OCR API expects: an http(s) URL is passed through verbatim, while a local path is read and base64-encoded. |
|
tui
Package tui implements the zai-client interactive terminal UI: a Bubble Tea v2 program with one tab per existing CLI command group, all wired to the same pkg/client, pkg/accounts, and pkg/coding services the non-interactive commands already use.
|
Package tui implements the zai-client interactive terminal UI: a Bubble Tea v2 program with one tab per existing CLI command group, all wired to the same pkg/client, pkg/accounts, and pkg/coding services the non-interactive commands already use. |
|
tui/accounts
Package accounts implements the TUI's Accounts tab: list, add, switch, and remove stored Z.AI account credentials via pkg/accounts.Store, the same store the "zai-client accounts" commands use.
|
Package accounts implements the TUI's Accounts tab: list, add, switch, and remove stored Z.AI account credentials via pkg/accounts.Store, the same store the "zai-client accounts" commands use. |
|
tui/chat
Package chat implements the TUI's Chat tab: a streaming conversation over pkg/client's ChatService, the same service "zai-client chat" uses.
|
Package chat implements the TUI's Chat tab: a streaming conversation over pkg/client's ChatService, the same service "zai-client chat" uses. |
|
tui/coding
Package coding implements the TUI's Coding tab: install/config status, auth, load, and unload for supported coding-agent tools (Claude Code, OpenCode, Crush, Factory Droid), backed by pkg/coding — the same package the "zai-client coding" commands use.
|
Package coding implements the TUI's Coding tab: install/config status, auth, load, and unload for supported coding-agent tools (Claude Code, OpenCode, Crush, Factory Droid), backed by pkg/coding — the same package the "zai-client coding" commands use. |
|
tui/media
Package media implements the TUI's Media tab: image generation, video generation, audio transcription, and OCR/layout parsing over pkg/client's ImagesService/VideosService/AudioService/LayoutService — the same services the "zai-client image/video/audio/ocr" commands use.
|
Package media implements the TUI's Media tab: image generation, video generation, audio transcription, and OCR/layout parsing over pkg/client's ImagesService/VideosService/AudioService/LayoutService — the same services the "zai-client image/video/audio/ocr" commands use. |
|
tui/models
Package models implements the TUI's Models tab: a browsable table of available Z.AI models, backed by the same ModelsService the "zai-client models" commands already use.
|
Package models implements the TUI's Models tab: a browsable table of available Z.AI models, backed by the same ModelsService the "zai-client models" commands already use. |
|
tui/tools
Package tools implements the TUI's Tools tab: three independent request/response forms (web search, web reader, tokenizer) over pkg/client's ToolsService, the same service the "zai-client tools" commands use.
|
Package tools implements the TUI's Tools tab: three independent request/response forms (web search, web reader, tokenizer) over pkg/client's ToolsService, the same service the "zai-client tools" commands use. |
|
tui/uimsg
Package uimsg holds tea.Msg types shared between the TUI root model and every screen subpackage.
|
Package uimsg holds tea.Msg types shared between the TUI root model and every screen subpackage. |
|
tui/uistyle
Package uistyle holds the shared lipgloss style vocabulary used by the root chrome and every screen subpackage, so pill/border/toast colors stay consistent without pkg/tui's screens importing pkg/tui itself (which would create an import cycle, since pkg/tui imports every screen).
|
Package uistyle holds the shared lipgloss style vocabulary used by the root chrome and every screen subpackage, so pill/border/toast colors stay consistent without pkg/tui's screens importing pkg/tui itself (which would create an import cycle, since pkg/tui imports every screen). |
|
tui/usage
Package usage implements the TUI's Usage tab: a live quota + token/tool usage dashboard, backed by the same QuotaService/UsageService the "zai-client usage"/"accounts quota"/"accounts usage" commands use.
|
Package usage implements the TUI's Usage tab: a live quota + token/tool usage dashboard, backed by the same QuotaService/UsageService the "zai-client usage"/"accounts quota"/"accounts usage" commands use. |
|
usageview
Package usageview holds pure, presentation-only helpers for rendering usage/quota data (time windows, relative timestamps, compact counters, and a density-heatmap ramp).
|
Package usageview holds pure, presentation-only helpers for rendering usage/quota data (time windows, relative timestamps, compact counters, and a density-heatmap ramp). |
|
pkg
|
|