zai-org/z-ai-sdk-python

zai-org/z-ai-sdk-python

Description: The official Python SDK for Z.ai's large model open interface, making it easier for developers to call Z.ai's open APIs.

Language: Python

License: MIT

Stars: 110

Forks: 28

Open issues: 8

Created: 2025-07-01T11:15:24Z

Pushed: 2026-06-03T09:59:27Z

Default branch: main

Fork: no

Archived: no

README:

Z.ai Open Platform Python SDK

[中文文档](README_CN.md) | English

Z.ai Open Platform The official Python SDK for Z.ai's large model open interface, making it easier for developers to call Z.ai's open APIs.

✨ Core Features

🤖 Chat Completions

• Standard Chat: Create chat completions with various models including glm-5.1
• Streaming Support: Real-time streaming responses for interactive applications
• Tool Calling: Function calling capabilities for enhanced AI interactions
• Multimodal Chat: Image understanding capabilities with vision models

🧠 Embeddings

• Text Embeddings: Generate high-quality vector embeddings for text
• Configurable Dimensions: Customizable embedding dimensions
• Batch Processing: Support for multiple inputs in a single request

🎥 Video Generation

• Text-to-Video: Generate videos from text prompts
• Image-to-Video: Create videos from image inputs
• Customizable Parameters: Control quality, duration, FPS, and size
• Audio Support: Optional audio generation for videos

🎵 Audio Processing

• Speech Transcription: Convert audio files to text
• Multiple Formats: Support for various audio file formats

🤝 Assistant API

• Conversation Management: Structured conversation handling
• Streaming Conversations: Real-time assistant interactions
• Metadata Support: Rich conversation context and user information

🔧 Advanced Tools

• Web Search: Integrated web search capabilities
• File Management: Upload, download, and manage files
• Batch Operations: Efficient batch processing for multiple requests
• Content Moderation: Built-in content safety and moderation
• Image Generation: AI-powered image creation

📦 Installation

Requirements

• Python: 3.8+
• Package Manager: pip

Install via pip

pip install zai-sdk

📋 Technical Specifications

Python Support

• Python Versions: 3.8, 3.9, 3.10, 3.11, 3.12
• Async Support: Full async/await compatibility
• Cross-platform: Windows, macOS, Linux support

Core Dependencies

| Package | Version | Purpose | |---------|---------|----------| | httpx | >=0.23.0 | HTTP client for API requests | | pydantic | >=1.9.0,=4.0.0 | Enhanced type hints support | | cachetools | >=4.2.2 | Caching utilities | | pyjwt | >=2.8.0 | JSON Web Token (JWT) handling |

🚀 Quick Start

Create API Key

Get API Key

• Overseas regions: Visit Z.ai Open Platform to get your API key
• Mainland China regions: Visit Zhipu AI Open Platform to get your API key

API BASE URL

• Mainland China regions: https://open.bigmodel.cn/api/paas/v4/
• Overseas regions: https://api.z.ai/api/paas/v4/

Usage Steps

1. Create client with API key 2. Call the corresponding API methods

For complete examples, please refer to the open platform API Reference and User Guide, and remember to replace with your own API key.

Basic Usage

from zai import ZaiClient, ZhipuAiClient

# For Overseas users, create the ZaiClient
client = ZaiClient(api_key="your-api-key")

# For Chinese users, create the ZhipuAiClient
client = ZhipuAiClient(api_key="your-api-key")

# Create chat completion
response = client.chat.completions.create(
model="glm-5.1",
messages=[
{"role": "user", "content": "Hello, Z.ai!"}
]
)
print(response.choices[0].message.content)

Client Configuration

The SDK supports multiple ways to configure API keys:

Environment Variables

export ZAI_API_KEY="your-api-key"
export ZAI_BASE_URL="https://api.z.ai/api/paas/v4/" # Optional

Code Configuration

from zai import ZaiClient, ZhipuAiClient

client = ZaiClient(
api_key="your-api-key",
base_url="https://api.z.ai/api/paas/v4/" # Optional
)

# if you want to use Zhipu's domain service
zhipu_client = ZhipuAiClient(
api_key="your-api-key",
base_url="https://open.bigmodel.cn/api/paas/v4/" # Optional
)

Advanced Configuration

Customize client behavior with additional parameters:

from zai import ZaiClient
import httpx

client = ZaiClient(
api_key="your-api-key",
timeout=httpx.Timeout(timeout=300.0, connect=8.0), # Request timeout
max_retries=3, # Retry attempts
base_url="https://api.z.ai/api/paas/v4/" # Custom API endpoint
)

📖 Usage Examples

Streaming Chat

from zai import ZaiClient

# Initialize client
client = ZaiClient(api_key="your-api-key")

# Create chat completion
response = client.chat.completions.create(
model='glm-5.1',
messages=[
{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'Tell me a story about AI.'},
],
stream=True,
)

for chunk in response:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end='')

Chat With Tool Call

from zai import ZaiClient

# Initialize client
client = ZaiClient(api_key="your-api-key")

# Create chat completion
response = client.chat.completions.create(
model='glm-5.1',
messages=[
{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'What is artificial intelligence?'},
],
tools=[
{
'type': 'web_search',
'web_search': {
'search_query': 'What is artificial intelligence?',
'search_result': True,
},
}
],
temperature=0.5,
max_tokens=2000,
)

print(response)

Multimodal Chat

from zai import ZaiClient
import base64

def encode_image(image_path):
"""Encode image to base64 format"""
with open(image_path, 'rb') as image_file:
return base64.b64encode(image_file.read()).decode('utf-8')

client = ZaiClient(api_key="your-api-key")
base64_image = encode_image('examples/test_multi_modal.jpeg')

response = client.chat.completions.create(
model='glm-5v-turbo',
messages=[
{
'role': 'user',
'content': [
{'type': 'text', 'text': "What's in this image?"},
{'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{base64_image}'}},
],
}
],…