Z.ai Open Platform Java SDK

中文文档 | English

Not yet released.

The official Java SDK for Z.ai and ZHIPU AI platforms, providing a unified interface to access powerful AI capabilities including chat completion, embeddings, image generation, audio processing, and more.

✨ Features

• 🚀 Type-safe API: All interfaces are fully type-encapsulated, no need to consult API documentation
• 🔧 Easy Integration: Simple and intuitive API design for quick integration
• ⚡ High Performance: Built with modern Java libraries for optimal performance
• 🛡️ Secure: Built-in authentication and token management
• 📦 Lightweight: Minimal dependencies for easy project integration

📦 Installation

Requirements

• Java 1.8 or higher
• Maven or Gradle
• Not supported on Android platform

Maven

Add the following dependency to your pom.xml:

<dependency>
    <groupId>ai.z</groupId>
    <artifactId>z-ai-sdk</artifactId>
    <version>0.0.1</version>
</dependency>

Gradle

Add the following dependency to your build.gradle (for Groovy DSL):

dependencies {
    implementation 'ai.z:z-ai-sdk:0.0.1'
}

Or build.gradle.kts (for Kotlin DSL):

dependencies {
    implementation("ai.z:z-ai-sdk:0.0.1")
}

📋 Dependencies

This SDK uses the following core dependencies:

Library	Version
OkHttp	4.12.0
Java JWT	4.4.0
Jackson	2.17.2
Retrofit2	2.11.0
RxJava	3.1.8
SLF4J	2.0.16

🚀 Quick Start

Basic Usage

1. Create a ZaiClient with your API credentials
2. Access services through the client
3. Call API methods with typed parameters

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

// Create client with API key, recommend export the ENV api-key
// export ZAI_API_KEY=your.api.key
ZaiClient client = ZaiClient.builder().build();

// Or set the api-key by code
ZaiClient client = ZaiClient.builder()
        .apiKey("your.api.key.your.api.secret")
        .build();

// Or create client for specific platform
ZaiClient zhipuClient = ZaiClient.ofZHIPU("your.api.key.your.api.secret").build();

Client Configuration

The SDK provides a flexible builder pattern for customizing your client:

ZaiClient client = ZaiClient.builder()
    .apiKey("your.api.key.your.api.secret")
    .baseUrl("https://api.z.ai/api/paas/v4/")
    .enableTokenCache()
    .tokenExpire(3600000) // 1 hour
    .connectionPool(10, 5, TimeUnit.MINUTES)
    .build();

💡 Examples

Chat Completion

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

// Create client
ZaiClient client = ZaiClient.builder()
    .apiKey("your.api.key.your.api.secret")
    .build();

// Create chat request
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
    .model(Constants.ModelChatGLM4)
    .messages(Arrays.asList(
        ChatMessage.builder()
            .role(ChatMessageRole.USER.value())
            .content("Hello, how are you?")
            .build()
    ))
    .stream(false)
    .temperature(0.7f)
    .maxTokens(1024)
    .build();

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

if (response.isSuccess()) {
    String content = response.getData().getChoices().get(0).getMessage().getContent();
    System.out.println("Response: " + content);
} else {
    System.err.println("Error: " + response.getMsg());
}

Streaming Chat

// Create streaming request
ChatCompletionCreateParams streamRequest = ChatCompletionCreateParams.builder()
    .model(Constants.ModelChatGLM4)
    .messages(Arrays.asList(
        ChatMessage.builder()
            .role(ChatMessageRole.USER.value())
            .content("Tell me a story")
            .build()
    ))
    .stream(true) // Enable streaming
    .build();

// Execute streaming request
ChatCompletionResponse response = client.chat().createChatCompletion(streamRequest);

if (response.isSuccess() && response.getFlowable() != null) {
    response.getFlowable().subscribe(
        data -> {
            // Handle streaming chunk
            if (data.getChoices() != null && !data.getChoices().isEmpty()) {
                String content = data.getChoices().get(0).getDelta().getContent();
                if (content != null) {
                    System.out.print(content);
                }
            }
        },
        error -> System.err.println("\nStream error: " + error.getMessage()),
        () -> System.out.println("\nStream completed")
    );
}

Function Calling

// Define function
ChatTool weatherTool = ChatTool.builder()
    .type(ChatToolType.FUNCTION.value())
    .function(ChatFunction.builder()
        .name("get_weather")
        .description("Get current weather for a location")
        .parameters(ChatFunctionParameters.builder()
            .type("object")
            .properties(Map.of(
                "location", Map.of(
                    "type", "string",
                    "description", "City name"
                )
            ))
            .required(Arrays.asList("location"))
            .build())
        .build())
    .build();

// Create request with function
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
    .model(Constants.ModelChatGLM4)
    .messages(Arrays.asList(
        ChatMessage.builder()
            .role(ChatMessageRole.USER.value())
            .content("What's the weather like in Beijing?")
            .build()
    ))
    .tools(Arrays.asList(weatherTool))
    .toolChoice("auto")
    .build();

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

Embeddings

import ai.z.openapi.service.embedding.*;

// Create embedding request
EmbeddingCreateParams request = EmbeddingCreateParams.builder()
    .model(Constants.ModelEmbedding3)
    .input(Arrays.asList("Hello world", "How are you?"))
    .build();

// Execute request
EmbeddingResponse response = client.embeddings().create(request);

if (response.isSuccess()) {
    response.getData().getData().forEach(embedding -> {
        System.out.println("Embedding: " + embedding.getEmbedding());
    });
}

Image Generation

import ai.z.openapi.service.image.*;

// Create image generation request
CreateImageRequest request = CreateImageRequest.builder()
    .model(Constants.ModelCogView3Plus)
    .prompt("A beautiful sunset over mountains")
    .size("1024x1024")
    .quality("standard")
    .n(1)
    .build();

// Execute request
ImageResponse response = client.images().generate(request);

if (response.isSuccess()) {
    response.getData().getData().forEach(image -> {
        System.out.println("Image URL: " + image.getUrl());
    });
}

Spring Boot Integration

@RestController
public class AIController {
    
    private final ZaiClient zaiClient;
    
    public AIController() {
        this.zaiClient = ZaiClient.builder()
            .apiKey("your.api.key.your.api.secret")
            .enableTokenCache()
            .build();
    }
    
    @PostMapping("/chat")
    public ResponseEntity<String> chat(@RequestBody ChatRequest request) {
        ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
            .model(Constants.ModelChatGLM4)
            .messages(Arrays.asList(
                ChatMessage.builder()
                    .role(ChatMessageRole.USER.value())
                    .content(request.getMessage())
                    .build()
            ))
            .build();
            
        ChatCompletionResponse response = zaiClient.chat().createChatCompletion(params);
        
        if (response.isSuccess()) {
            String content = response.getData().getChoices().get(0).getMessage().getContent();
            return ResponseEntity.ok(content);
        } else {
            return ResponseEntity.badRequest().body(response.getMsg());
        }
    }
}

🔧 Available Services

The ZaiClient provides access to comprehensive AI services:

Service	Description	Key Features
Chat	Text generation and conversation	Streaming, function calling, async support
Embeddings	Text embeddings generation	Multiple embedding models
Images	Image generation and processing	CogView models, various sizes
Audio	Speech synthesis and recognition	Text-to-speech, speech-to-text
Files	File management and processing	Upload, download, batch processing
Assistants	AI assistant management	Create, configure, and manage assistants
Agents	Agent-based completions	Specialized agent interactions
Knowledge	Knowledge base operations	Document indexing and retrieval
Fine-tuning	Model customization	Train custom models
Batch	Batch processing	Bulk operations
Web Search	Web search integration	Real-time web information
Videos	Video processing	Video analysis and generation

🎯 Supported Models

Text Generation

• glm-4-plus - Enhanced GLM-4 with improved capabilities
• glm-4 - Standard GLM-4 model
• glm-4-air - Lightweight version for speed
• glm-4-flash - Ultra-fast response model
• glm-4-long - Optimized for long-context conversations
• glm-4-voice - Specialized for voice interactions

Vision Models

• glm-4v-plus - Enhanced vision model
• glm-4v - Standard vision model

Image Generation

• cogview-3-plus - Enhanced image generation
• cogview-3 - Standard image generation

Embeddings

• embedding-3 - Latest embedding model
• embedding-2 - Previous generation embedding

Specialized

• charglm-3 - Character interaction model
• cogtts - Text-to-speech model

📈 Release Notes

For detailed release notes and version history, please see Release-Note.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request.

📞 Support

For questions and support:

• Visit Z.ai Platform
• Visit ZHIPU AI Open Platform
• Check our Architecture Documentation