1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
//! # ZAI-RS: Zhipu AI Rust SDK
//!
//! `zai-rs` is a type-safe Rust SDK providing full coverage of the Zhipu AI
//! (BigModel) API. Strongly-typed clients and models span chat completions,
//! image generation, speech recognition, text embeddings, knowledge-base
//! management, and more.
//!
//! # Capabilities
//!
//! | Capability | Description | Module |
//! |------------|-------------|--------|
//! | Chat completions | Sync / async / streaming text, vision, voice | [`model`] |
//! | Image generation | Text-to-image | [`model::gen_image`] |
//! | Video generation | Async text-to-video | [`model::gen_video_async`] |
//! | Text-to-speech | Audio synthesis | [`model::text_to_audio`] |
//! | Speech-to-text | Audio transcription | [`model::audio_to_text`] |
//! | Voice cloning | Voice clone, list, delete | [`model::voice_clone`] |
//! | Text embeddings | Embeddings, reranking, tokenization | [`model::text_embedded`] |
//! | Content moderation | Safety analysis | [`model::moderation`] |
//! | OCR | Handwriting recognition | [`model::ocr`] |
//! | File management | Upload, list, content, delete | [`mod@file`] |
//! | Batch processing | Create, list, retrieve, cancel | [`batches`] |
//! | Knowledge base | CRUD, document upload, retrieval | [`knowledge`] |
//! | Tool calling | Function calling, web search, file parsing | [`tool`] |
//! | Agent | Agent creation & management | [`agent`] |
//! | Tool execution framework | Dynamic registration, execution, caching | [`toolkits`] |
//! | Real-time | WebSocket audio/video (GLM-Realtime) | [`realtime`] |
//! | Coding Plan usage | GLM Coding Plan quota / 余量查询 | [`usage`] |
//!
//! # Module Structure
//!
//! - [`client`] — HTTP client, connection pool, retry strategy, error types
//! - [`model`] — Data models, request/response types, model definitions, SSE
//! parsing
//! - [`mod@file`] — File management (upload, list, content, delete)
//! - [`batches`] — Batch processing (create, list, retrieve, cancel)
//! - [`knowledge`] — Knowledge-base management (CRUD, document upload,
//! retrieval)
//! - [`tool`] — Tool implementations (web search, file parsing)
//! - [`agent`] — Agent API (creation, chat, history)
//! - [`toolkits`] — Tool execution framework (registration, execution, caching,
//! RMCP bridge)
//! - [`realtime`] — Real-time audio/video communication (WebSocket,
//! experimental)
//! - [`usage`] — Coding Plan usage / quota query (GLM Coding Plan 余量查询)
//!
//! # Quick Start
//!
//! ```rust,no_run
//! use zai_rs::{client::http::*, model::*};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let model = GLM4_5_flash {};
//! let key = std::env::var("ZHIPU_API_KEY").unwrap();
//! let client = ChatCompletion::new(model, TextMessage::user("Hello"), key);
//! let _resp = client.post().await?;
//! Ok(())
//! }
//! ```
//!
//! # Streaming Responses
//!
//! ```rust,no_run
//! use zai_rs::{client::http::*, model::*};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let model = GLM4_5_flash {};
//! let key = std::env::var("ZHIPU_API_KEY").unwrap();
//! let mut client =
//! ChatCompletion::new(model, TextMessage::user("Hello"), key).enable_stream();
//! client
//! .stream_sse_for_each(|data| {
//! print!("{}", String::from_utf8_lossy(data));
//! })
//! .await?;
//! Ok(())
//! }
//! ```
//!
//! # Feature Flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | (default) | enabled | Core API functionality |
//! | `rmcp-kits` | disabled | Enable RMCP protocol bridge for MCP tool calling |
//! | `web-example` | disabled | Enable axum/tower dependencies for web examples |
//!
//! Enable in `Cargo.toml`:
//! ```toml
//! [dependencies]
//! zai-rs = { version = "0.2", features = ["rmcp-kits"] }
//! ```
//!
//! # Error Handling
//!
//! All API calls return [`ZaiResult`](client::error::ZaiResult)`<T>`,
//! unified under the [`ZaiError`](client::error::ZaiError) enum:
//!
//! - `ApiError` — Business-level API error (with code and message)
//! - `NetworkError` — Network / timeout error
//! - `JsonError` — JSON serialization / deserialization error
//! - `RateLimitError` — Rate-limit or quota exceeded
//! - `AuthError` — Authentication / authorization error
//!
//! # Design Principles
//!
//! - **Compile-time type safety** — trait bounds and type-state patterns ensure
//! model/message compatibility at compile time
//! - **Zero-cost abstractions** — marker traits and type-state patterns impose
//! no runtime overhead
//! - **Consistent API style** — all API clients follow a uniform builder
//! pattern and implement the `HttpClient` trait
pub use ;
pub use ;