Z.AI

https://docs.z.ai/
Admin
Z.AI is an AI open platform offering a suite of large language models (LLMs), vision language...
Tokens:191,060
Snippets:1,485
Trust Score:9.7
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Complete Installation: Install all packages and verify

Source: https://docs.z.ai/guides/develop/langchain/introduction

Install all related packages at once and verify the installation by printing the LangChain version.

```bash
# Install all related packages at once
pip install langchain langchain-openai langchainhub httpx_sse

# Verify installation
python -c "import langchain; print(langchain.__version__)"
```

--------------------------------

### Python SDK - Install and Verify

Source: https://docs.z.ai/guides/capabilities/thinking

Instructions for installing the zai-sdk Python package and verifying the installation.

```APIDOC
## Python SDK - Install and Verify

### Description
Install the zai-sdk Python package and verify the installation.

### Installation
```bash
pip install zai-sdk
# Or specify version
pip install zai-sdk==0.2.3
```

### Verification
```python
import zai
print(zai.__version__)
```
```

--------------------------------

### Basic Installation: Install LangChain and OpenAI compatible package

Source: https://docs.z.ai/guides/develop/langchain/introduction

Install LangChain and related dependencies including langchain, langchainhub, httpx_sse, and the OpenAI compatible package langchain-openai.

```bash
# Install LangChain and related dependencies
pip install langchain langchainhub httpx_sse

# Install OpenAI compatible package
pip install langchain-openai
```

--------------------------------

### Verify Installation

Source: https://docs.z.ai/guides/tools/stream-tool

Verify that the zai-sdk is installed correctly by importing it and printing the version.

```APIDOC
## Verify Installation

### Description
Check that the zai-sdk package is installed and accessible.

### Code
```python
import zai
print(zai.__version__)
```
```

--------------------------------

### Install and run Coding Tool Helper globally

Source: https://docs.z.ai/devpack/extension/coding-tool-helper

For frequent use. Install globally, then launch with coding-helper or chelper. If npm install fails with permission denied, add sudo (macOS/Linux) or run terminal as administrator (Windows).

```bash
## Install @z_ai/coding-helper globally
npm install -g @z_ai/coding-helper
## Then run coding-helper or chelper
coding-helper
```

--------------------------------

### Install OpenAI Node.js SDK

Source: https://docs.z.ai/api-reference/introduction

Installs the OpenAI Node.js SDK using npm or yarn.

```bash
# Install or upgrade to latest version
npm install openai

# Or using yarn
yarn add openai
```

--------------------------------

### Install SDK

Source: https://docs.z.ai/guides/tools/stream-tool

Install the zai-sdk package via pip, either the latest version or a specific version.

```APIDOC
## Install SDK

### Description
Install the zai-sdk package to use the Z.ai API.

### Command
```bash
pip install zai-sdk
```

### Optional: Specify Version
```bash
pip install zai-sdk==0.2.3
```
```

--------------------------------

### Basic Conversation Example (Python SDK)

Source: https://docs.z.ai/guides/capabilities/cache

Python SDK example showing two requests: the first establishes a cache, the second reuses the system prompt cache. Prints reply, total tokens, and cached tokens.

```python
from zai import ZaiClient

# Initialize client
client = ZaiClient(api_key='Your API key')

# First request - establish cache
response1 = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {
            "role": "system",
            "content": "You are a professional technical documentation assistant, skilled at explaining complex technical concepts. Please answer user questions with clear and concise language, and provide practical code examples."
        },
        {
            "role": "user",
            "content": "What is RESTful API?"
        }
    ]
)

print("First request result:")
print(f"Reply: {response1.choices[0].message.content}")
print(f"Total tokens: {response1.usage.total_tokens}")
print(f"Cached tokens: {response1.usage.prompt_tokens_details.cached_tokens if hasattr(response1.usage, 'prompt_tokens_details') else 0}")

# Second request - reuse system prompt cache
response2 = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {
            "role": "system",
            "content": "You are a professional technical documentation assistant, skilled at explaining complex technical concepts. Please answer user questions with clear and concise language, and provide practical code examples."  # Same system prompt
        },
        {
            "role": "user",
            "content": "What are the differences between GraphQL and RESTful API?"
        }
    ]
)

print("\nSecond request result:")
print(f"Reply: {response2.choices[0].message.content}")
print(f"Total tokens: {response2.usage.total_tokens}")
print(f"Cached tokens: {response2.usage.prompt_tokens_details.cached_tokens if hasattr(response2.usage, 'prompt_tokens_details') else 0}")
```

--------------------------------

### Install OpenAI Python SDK using pip

Source: https://docs.z.ai/guides/develop/openai/python

Install or upgrade the OpenAI SDK to version 1.0 or higher using pip, then verify the installation by printing the installed version.

```bash
# Install or upgrade to latest version
pip install --upgrade 'openai>=1.0'

# Verify installation
python -c "import openai; print(openai.__version__)"
```

--------------------------------

### Install Official Python SDK (zai-sdk)

Source: https://docs.z.ai/api-reference/introduction

Installs the official Z.AI Python SDK using pip. The latest version is installed by default, or a specific version can be specified.

```bash
# Install latest version
pip install zai-sdk

# Or specify version
pip install zai-sdk==0.2.3
```

--------------------------------

### Function Calling Example in Java

Source: https://docs.z.ai/guides/develop/java/introduction

Complete example showing how to define function tools (get_weather, get_stock_price), create a chat completion request with toolChoice 'auto', and handle tool calls in the response. Uses ZaiClient with API key from environment variable ZAI_API_KEY and model 'glm-5.3'.

```java
import ai.z.openapi.ZaiClient;
import ai.z.openapi.service.model.*;
import ai.z.openapi.core.Constants;
import java.util.*;

public class FunctionCallingExample {
    
    // Simulate weather API
    public static Map<String, Object> getWeather(String location, String date) {
        Map<String, Object> weather = new HashMap<>();
        weather.put("location", location);
        weather.put("date", date != null ? date : "today");
        weather.put("weather", "sunny");
        weather.put("temperature", "25°C");
        weather.put("humidity", "60%");
        return weather;
    }
    
    // Simulate stock API
    public static Map<String, Object> getStockPrice(String symbol) {
        Map<String, Object> stock = new HashMap<>();
        stock.put("symbol", symbol);
        stock.put("price", 150.25);
        stock.put("change", "+2.5%");
        return stock;
    }
    
    public static void main(String[] args) {
        ZaiClient client = ZaiClient.builder().ofZAI()
            .apiKey(System.getenv("ZAI_API_KEY"))
            .build();
        
        // Define function tools
        Map<String, ChatFunctionParameterProperty> properties = new HashMap<>();
        ChatFunctionParameterProperty locationProperty = ChatFunctionParameterProperty
                .builder().type("string").description("City name, for example: Beijing").build();
        properties.put("location", locationProperty);
        ChatFunctionParameterProperty unitProperty = ChatFunctionParameterProperty
                .builder().type("string").enums(Arrays.asList("celsius", "fahrenheit")).build();
        properties.put("unit", unitProperty);
        ChatTool weatherTool = ChatTool.builder()
                .type(ChatToolType.FUNCTION.value())
                .function(ChatFunction.builder()
                        .name("get_weather")
                        .description("Get weather information for a specified location")
                        .parameters(ChatFunctionParameters.builder()
                                .type("object")
                                .properties(properties)
                                .required(Collections.singletonList("location"))
                                .build())
                        .build())
                .build();
        
        // Create request
        ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
                .model("glm-5.3")
                .messages(Collections.singletonList(
                        ChatMessage.builder()
                                .role(ChatMessageRole.USER.value())
                                .content("How's the weather in Beijing today?")
                                .build()
                ))
                .tools(Collections.singletonList(weatherTool))
                .toolChoice("auto")
                .build();

        // Send request
        ChatCompletionResponse response = client.chat().createChatCompletion(request);

        if (response.isSuccess()) {
            // Handle function calling
            ChatMessage assistantMessage = response.getData().getChoices().get(0).getMessage();
            if (assistantMessage.getToolCalls() != null && !assistantMessage.getToolCalls().isEmpty()) {
                for (ToolCalls toolCall : assistantMessage.getToolCalls()) {
                    String functionName = toolCall.getFunction().getName();

                    if ("get_weather".equals(functionName)) {
                        Map<String, Object> result = getWeather("Beijing", null);
                        System.out.println("Weather info: " + result);
                    }
                }
            } else {
                System.out.println(assistantMessage.getContent());
            }
        } else {
            System.err.println("Error: " + response.getMsg());
        }
    }
}
```

--------------------------------

### One-click Installation Command for Claude Desktop

Source: https://docs.z.ai/devpack/mcp/vision-mcp-server

Use this command to install the Z.AI MCP server via Claude Desktop. Replace 'your_api_key' with your actual API key. If you forget to replace it, uninstall the old server first.

```bash
claude mcp add -s user zai-mcp-server --env Z_AI_API_KEY=your_api_key Z_AI_MODE=ZAI -- npx -y "@z_ai/mcp-server"
```

--------------------------------

### Install zai-sdk via pip

Source: https://docs.z.ai/guides/vlm/glm-ocr

Installs the latest version of the zai-sdk Python package, or a specific version (0.2.3) if needed.

```bash
# Install the latest version
pip install zai-sdk
# Or specify a version
pip install zai-sdk==0.2.3
```

--------------------------------

### Complete Function Calling example with ZaiClient

Source: https://docs.z.ai/guides/capabilities/function-calling

This example demonstrates how to define a function tool (get_weather), make a chat completion request with tools and tool_choice='auto', handle the tool_calls response, and return the function result to the model for a final answer. It uses the glm-5.3 model and requires a valid API key.

```python
import json
from zai import ZaiClient

# Initialize client
client = ZaiClient(api_key='your_api_key')

# Define weather query function
def get_weather(city: str) -> dict:
    """Get weather information for specified city"""
    # This should call a real weather API
    weather_data = {
        "city": city,
        "temperature": "22°C",
        "condition": "Sunny",
        "humidity": "65%",
        "wind_speed": "5 km/h"
    }
    return weather_data

# Define function tools
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather information for specified city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g.: Beijing, Shanghai"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# Make conversation request
response = client.chat.completions.create(
    model="glm-5.3",  # Use model that supports function calling
    messages=[
        {"role": "user", "content": "How's the weather in Beijing today?"}
    ],
    tools=tools,         # Pass function tools
    tool_choice="auto"   # Automatically choose whether to call functions
)

# Handle function calls
message = response.choices[0].message
messages = [{"role": "user", "content": "How's the weather in Beijing today?"}]
messages.append(message.model_dump())

if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "get_weather":
            # Parse parameters and call function
            args = json.loads(tool_call.function.arguments)
            weather_result = get_weather(args.get("city"))
            
            # Return function result to model
            messages.append({
                "role": "tool",
                "content": json.dumps(weather_result, ensure_ascii=False),
                "tool_call_id": tool_call.id
            })
    
    # Get final answer
    final_response = client.chat.completions.create(
        model="glm-5.3",
        messages=messages,
        tools=tools
    )
    
    print(final_response.choices[0].message.content)
else:
    print(message.content)
```

--------------------------------

### Code Debugging Example

Source: https://docs.z.ai/devpack/quick-start

Describe an issue encountered, such as a 404 error, to get help checking the code.

```text
# Describe the issue encountered
My API request returns a 404 error. Please help me check the code.
```

--------------------------------

### Python requests example for Web Search API

Source: https://docs.z.ai/api-reference/tools/web-search

Uses the requests library to POST the same payload to the Web Search API. The response is printed as text. Requires the requests library to be installed.

```python
import requests

url = "https://api.z.ai/api/paas/v4/web_search"

payload = {
    "search_engine": "search-prime",
    "search_query": "<string>",
    "count": 25,
    "search_domain_filter": "<string>",
    "request_id": "<string>",
    "user_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Install PyJWT

Source: https://docs.z.ai/guides/develop/http/introduction

Installation command for PyJWT, required for JWT token generation.

```bash
pip install PyJWT
```

--------------------------------

### Coding Tool Helper Command List

Source: https://docs.z.ai/devpack/extension/coding-tool-helper

Commands to initialize the wizard, manage language and API keys, run diagnostics, and show help/version. Use `coding-helper` or `chelper` with these arguments.

```bash
# Launch the initialization wizard
coding-helper init

# Language management
coding-helper lang show              # Display the current language
coding-helper lang set en_US         # Switch to English
coding-helper lang --help            # View language command help

# API key management
coding-helper auth                   # Configure the key interactively
coding-helper auth glm_coding_plan_global <token>     # Select the Global plan and set the key directly
coding-helper auth revoke            # Remove the stored key
coding-helper auth reload claude     # Load the latest plan into Claude Code
coding-helper auth --help            # View auth command help

coding-helper doctor                 # Check system configuration and tool status
coding-helper --help                 # Show help information
coding-helper --version              # Show version
```

--------------------------------

### Python: Configure web_search tool and call chat.completions

Source: https://docs.z.ai/guides/tools/web-search

Initializes ZaiClient with an API key, defines a web_search tool with parameters like search_engine, search_prompt, and filters, then sends a user message to the chat.completions endpoint with model glm-4-air. The response is printed.

```python
from zai import ZaiClient

# Initialize the ZaiClient client
client = ZaiClient(api_key="YourAPIKey")

# Define tool parameters
tools = [{
    "type": "web_search",
    "web_search": {
         "enable": "True",
         "search_engine": "search-prime",
         "search_result": "True",
         "search_prompt": "You are a financial analyst. Please use concise language to summarize the key information in {{search_result}} from the web search, ranked by importance and citing the source date. Today's date is April 11, 2025.",
         "count": "5",
         "search_domain_filter": "www.sohu.com",
         "search_recency_filter": "noLimit",
         "content_size": "high"
    }
}]

# Define user message
messages = [{
    "role": "user",
    "content": "Key financial events, policy changes, and market data in April 2025"
}]

# Call the API to get a response
response = client.chat.completions.create(
    model="glm-4-air",  # Model identifier
    messages=messages,  # User messages
    tools=tools         # Tool parameters
)

# Print the response result
print(response)
```

--------------------------------

### Verify Official Python SDK Installation

Source: https://docs.z.ai/api-reference/introduction

Verifies that the zai-sdk package is installed and prints its version.

```python
import zai
print(zai.__version__)
```

--------------------------------

### Install OpenAI Python SDK using poetry

Source: https://docs.z.ai/guides/develop/openai/python

Add the OpenAI SDK version 1.0 or higher as a dependency using Poetry.

```bash
poetry add "openai>=1.0"
```

--------------------------------

### Create ZaiClient with direct API key

Source: https://docs.z.ai/guides/develop/python/introduction

Initialize a ZaiClient by setting the API key directly. Note: the source contains a duplicate import of ZaiClient.

```python
from zai import ZaiClient, ZaiClient

# Set API Key directly
client = ZaiClient(api_key="abc123.def456")
```

--------------------------------

### Verify OpenAI Python SDK Installation

Source: https://docs.z.ai/api-reference/introduction

Verifies that the OpenAI Python SDK is installed and prints its version.

```bash
python -c "import openai; print(openai.__version__)"
```

--------------------------------

### Advanced Configuration with Custom HTTP Client

Source: https://docs.z.ai/guides/develop/python/introduction

This example shows how to configure the ZaiClient with a custom httpx.Client, setting connection limits and timeouts. It also demonstrates setting a custom base_url, a longer timeout, and max_retries for the client.

```python
import httpx
from zai import ZaiClient

# Custom HTTP client
httpx_client = httpx.Client(
    limits=httpx.Limits(
        max_keepalive_connections=20,
        max_connections=100
    ),
    timeout=30.0
)

# Create client with custom configuration
client = ZaiClient(
    api_key="your-api-key",
    base_url="https://api.z.ai/api/paas/v4/",
    timeout=httpx.Timeout(timeout=300.0, connect=8.0),
    max_retries=3,
    http_client=httpx_client
)
```

--------------------------------

### Create ZaiClient with direct API key setting

Source: https://docs.z.ai/guides/develop/java/introduction

Shows how to create a ZaiClient by directly setting the API key in code, which is useful when the environment variable is not set or when you want to hardcode the key for testing.

```java
import ai.z.openapi.ZaiClient;

public class QuickStart {
    public static void main(String[] args) {
        // Set API Key directly
        ZaiClient client = ZaiClient.builder().ofZAI()
            .apiKey("YOUR_API_KEY")
            .build();
    }
}
```

--------------------------------

### Install OpenAI Python SDK

Source: https://docs.z.ai/api-reference/introduction

Installs or upgrades the OpenAI Python SDK to version 1.0 or later, which is required for compatibility with the Z.AI API.

```bash
# Install or upgrade to latest version
pip install --upgrade 'openai>=1.0'
```

--------------------------------

### OpenAI Python SDK Chat Completion Example

Source: https://docs.z.ai/api-reference/introduction

Uses the OpenAI Python SDK with a custom base URL to send a chat completion request to the Z.AI API. The example uses the glm-5.3 model.

```python
from openai import OpenAI

client = OpenAI(
    api_key="your-Z.AI-api-key",
    base_url="https://api.z.ai/api/paas/v4/"
)

completion = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {"role": "system", "content": "You are a smart and creative novelist"},
        {"role": "user", "content": "Please write a short fairy tale story as a fairy tale master"}
    ]
)

print(completion.choices[0].message.content)
```
Tokens:
Raw