Z AI SDK 使用指南

这个指南说明如何使用 z-ai-sdk 与自定义 AI 接口进行交互，包括聊天对话和图片生成功能。

1. 配置

在使用 SDK 之前，您必须创建一个名为 .z-ai-config 的配置文件。SDK 会按以下顺序搜索此文件：

当前项目目录 (./.z-ai-config)
用户主目录 (~/.z-ai-config)
系统目录 (/etc/.z-ai-config)

配置文件必须是有效的 JSON 格式，具有以下结构：

{
  "baseUrl": "YOUR_API_BASE_URL",
  "apiKey": "YOUR_API_KEY",
  "chatId": "OPTIONAL_CHAT_ID",
  "userId": "OPTIONAL_USER_ID"
}

2. 安装

npm install z-ai-web-dev-sdk

3. 聊天对话功能

以下是导入和使用 SDK 创建聊天对话的简单示例：

import ZAI from 'z-ai-web-dev-sdk';

async function main() {
  try {
    // 实例化类时会自动加载配置
    const zai = await ZAI.create();

    const completion = await zai.chat.completions.create({
      // model 是可选的
      // model: 'your-model-name',
      messages: [
        {
          role: 'system',
          content: 'You are a helpful assistant.'
        },
        {
          role: 'user',
          content: 'Hello, who are you?'
        }
      ],
      // 其他参数如 temperature, max_tokens 等可以在这里添加
    });

    console.log('完整 API 响应:', completion);

    // 示例：从第一个选择中访问消息内容
    const messageContent = completion.choices[0]?.message?.content;
    if (messageContent) {
      console.log('助手回复:', messageContent);
    }

  } catch (error) {
    console.error('发生错误:', error.message);
  }
}

main();

4. 图片生成功能

SDK 现在支持图片生成功能，返回 base64 格式的图片数据：

import ZAI from 'z-ai-web-dev-sdk';

async function generateImage() {
  try {
    const zai = await ZAI.create();

    const response = await zai.images.generations.create({
      model: 'cogview-4-250304', // 必需：模型代码
      prompt: '一只可爱的小猫咪', // 必需：图片描述
      quality: 'hd', // 可选：standard 或 hd (默认: standard)
      size: '1024x1024', // 可选：图片尺寸 (默认: 1024x1024)
      user_id: 'your-user-id' // 可选：用户ID
    });

    console.log('图片生成时间:', new Date(response.created * 1000));

    // 获取 base64 格式的图片数据
    const imageBase64 = response.data[0].base64;
    console.log('图片 base64 数据:', imageBase64);

    // 可以直接在 HTML 中使用：
    // <img src="${imageBase64}" alt="Generated Image" />

  } catch (error) {
    console.error('图片生成失败:', error.message);
  }
}

generateImage();

支持的模型和参数

模型: cogview-4-250304 (最新), cogview-4, cogview-3-flash
质量:
- standard: 快速生成，5-10 秒
- hd: 更精细，更详细，约 20 秒
尺寸: 1024x1024, 768x1344, 864x1152, 1344x768, 1152x864, 1440x720, 720x1440

5. CLI 工具

SDK 提供了一个命令行工具，可以直接生成图片并保存到指定路径。

安装 CLI

全局安装 SDK 以使用 CLI 命令：

npm install -g z-ai-web-dev-sdk

使用 CLI

# 基本用法
z-ai-generate --prompt "一只可爱的小猫" --output "./cat.png"

# 使用短参数
z-ai-generate -p "美丽的风景" -o "./landscape.jpg"

# 指定质量和尺寸
z-ai-generate -p "现代建筑设计" -o "./building.png" -q hd -s 1344x768

# 指定模型
z-ai-generate -p "抽象艺术" -o "./art.png" -m cogview-4-250304

# 查看帮助
z-ai-generate --help

CLI 参数说明

--prompt, -p <文本>: 必需 - 图片描述文本
--output, -o <路径>: 必需 - 输出图片文件路径
--model, -m <模型>: 可选 - 模型代码 (默认: cogview-4-250304)
--quality, -q <质量>: 可选 - 图片质量 (standard|hd, 默认: standard)
--size, -s <尺寸>: 可选 - 图片尺寸 (默认: 1024x1024)
--help, -h: 显示帮助信息

CLI 示例

# 生成高质量风景图
z-ai-generate \
  --prompt "雪山湖泊，倒影清晰，4K高清" \
  --output "./mountain_lake.png" \
  --quality hd \
  --size 1344x768

# 生成人物肖像
z-ai-generate \
  -p "专业商务人士头像，正装，白色背景" \
  -o "./portraits/business_portrait.jpg" \
  -q hd

# 快速生成图标
z-ai-generate \
  -p "简约科技图标，蓝色渐变" \
  -o "./icons/tech_icon.png" \
  -q standard \
  -s 1024x1024

6. 错误处理

try {
  const zai = await ZAI.create();
  // API 调用...
} catch (error) {
  if (error.message.includes('Configuration file not found')) {
    console.error('请创建 .z-ai-config 配置文件');
  } else if (error.message.includes('API request failed')) {
    console.error('API 请求失败，请检查网络连接和配置');
  } else {
    console.error('未知错误:', error.message);
  }
}

7. TypeScript 支持

SDK 完全支持 TypeScript，提供完整的类型定义：

import ZAI, { CreateChatCompletionBody, CreateImageGenerationBody, ImageGenerationResponse } from 'z-ai-web-dev-sdk';

const completion: CreateChatCompletionBody = {
  messages: [
    { role: 'user', content: 'Hello' }
  ]
};

const imageRequest: CreateImageGenerationBody = {
  model: 'cogview-4-250304',
  prompt: '美丽的花朵',
  quality: 'hd'
};

8. 注意事项

确保配置文件中的 baseUrl 和 apiKey 正确
图片 URL 链接有效期为 30 天，建议及时下载保存
CLI 工具会自动创建输出目录（如果不存在）
生成的图片格式取决于 API 返回的内容类型
建议在生产环境中添加适当的错误处理和重试机制

Détail du package

z-ai-web-dev-sdk

readme