z-ai-web-dev-sdk/README.md

SDK for Z AI Web Dev

# Z AI SDK 使用指南

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

## 1. 配置

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

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

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

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

## 2. 安装

```bash
npm install z-ai-web-dev-sdk
```

## 3. 聊天对话功能

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

```javascript
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 格式的图片数据：

```javascript
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 命令：

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

### 使用 CLI

```bash
# 基本用法
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 示例

```bash
# 生成高质量风景图
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. 错误处理

```javascript
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，提供完整的类型定义：

```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 返回的内容类型
- 建议在生产环境中添加适当的错误处理和重试机制