Z.AI图像和视频生成MCP服务器
A. 模型上下文协议(MCP) 该服务器为LLM应用程序提供对Z.AI图像和视频生成模型的访问。
特性
- 图像生成:用于生成高质量图像的GLM Image和CogView-4型号
- 视频生成:用于AI视频创建的CogVideoX-3、Vidu Q1和Vidu 2模型
- 多种输入模式:文本到图像/视频、图像到视频、开始到结束帧动画
- 异步处理:提交长时间运行的任务并轮询结果
- 自动下载:在一次操作中生成和下载
- 自动检索:具有指数回退的内置重试逻辑
- 全面验证:带有明确错误消息的输入验证
- 类型安全:完全支持TypeScript,具有详细的类型定义
安装```bash
npm install GeorgH93/z_ai_image_gen_mcp
## 配置
将Z.AI API键设置为环境变量:```bash
export ZAI_API_KEY=your_api_key_here
从获取API密钥 Z.AI API密钥页 或注册 GLM 编程计划.
可选配置
| 环境变量 | 描述 | 默认值 |
|---|---|---|
ZAI_API_BASE_URL |
API基本URL | https://api.z.ai/api |
ZAI_DEFAULT_MODEL |
默认型号 | glm-image |
ZAI_DEFAULT_SIZE |
默认图像大小 | 1280x1280 |
ZAI_REQUEST_TIMEOUT |
请求超时(ms) | 60000 |
ZAI_MAX_RETRIES |
最大重试次数 | 3 |
ZAI_RETRY_DELAY |
初始重试延迟(ms) | 1000 |
用法
使用克劳德桌面
添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上):```json
{
"mcpServers": {
"z-ai-image": {
"command": "npx",
"args": ["z-ai-image-mcp"],
"env": {
"ZAI_API_KEY": "your_api_key_here"
}
}
}
}
### 与其他MCP客户端
直接运行服务器:```bash
npx z-ai-image-mcp
或者以编程方式:```typescript
import { createServer, loadConfig } from 'z-ai-image-mcp';
const config = loadConfig();
const server = createServer(config);
// Connect to your transport...
### 使用OpenCode
添加到您的OpenCode配置(`opencode.json` 或 `opencode.jsonc` 在项目根目录中):```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"z-ai-image": {
"type": "local",
"command": ["npx", "z-ai-image-mcp"],
"enabled": true,
"environment": {
"ZAI_API_KEY": "your_api_key_here"
}
}
}
}
或者使用环境变量引用:```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"z-ai-image": {
"type": "local",
"command": ["npx", "z-ai-image-mcp"],
"enabled": true,
"environment": {
"ZAI_API_KEY": "{env:ZAI_API_KEY}"
}
}
}
}
**使用OpenCode提示:**```
Generate a professional logo for a tech startup. use z-ai-image
或添加到您的 AGENTS.md:``markdown
When generating images, use thez-ai-image` MCP server tools.
**每个代理配置(可选):**
要仅为特定代理启用MCP服务器,请执行以下操作:```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"z-ai-image": {
"type": "local",
"command": ["npx", "z-ai-image-mcp"],
"enabled": true,
"environment": {
"ZAI_API_KEY": "{env:ZAI_API_KEY}"
}
}
},
"tools": {
"z-ai-image*": false
},
"agent": {
"design-agent": {
"tools": {
"z-ai-image*": true
}
}
}
}
可用工具
1. list_models
列出所有可用的图像生成模型及其功能。```
Use this tool to discover available models, their features, and recommended settings.
### 2. `generate_image`
从文本提示同步生成图像。
**参数:**
- `prompt` (必填):图像的文字描述(最多4000个字符)
- `model` (可选): `glm-image` 或 `cogview-4-250304` (默认值: `glm-image`)
- `size` (可选):图像尺寸。, `1280x1280` (默认值: `1280x1280`)
- `quality` (可选): `hd` 或 `standard` (默认值: `hd` GLM图像)
- `user_id` (可选):用于防止滥用的最终用户ID(6-128个字符)
**例子:**```
Generate an image of a cute kitten sitting on a windowsill with a sunset background.
3. generate_image_async
启动异步图像生成任务。返回轮询的任务ID。
参数:
prompt(必填):图像的文字描述model(可选):仅限glm-image支持异步(默认:glm-image)size(可选):图像尺寸(默认值:1280x1280)quality(可选):仅限hd支持异步(默认:hd)user_id(可选):用于防止滥用的最终用户ID
例子:```
Start async generation of a complex poster design.
### 4. `get_async_result`
检索异步图像生成任务的结果。
**参数:**
- `task_id` (必填):任务ID来自 `generate_image_async`
**例子:**```
Check the status of task ID "task-12345".
5. download_image
从URL下载图像并将其作为base64返回或保存到文件中。
参数:
url(必填):要下载的图像的URL(例如,从generate_image或get_async_result)output(可选):base64或file_output(默认值:base64)file_output(可选):保存图像文件的绝对路径(如果输出为file_output).例子:/path/to/image.png
输出模式:
base64:直接以base64格式返回图像数据(如果>1MB,则自动切换到文件)file_output:将映像保存到指定路径的磁盘
例子:```
Download the generated image and save it to /home/user/images/logo.png
> **注:** Z.AI图像URL将在30天后过期。使用此工具下载并永久存储图像。
### 6. `generate_and_download_image` ⭐ 推荐
生成图像并在一次操作中自动下载。当您需要立即获取图像数据时,这是最方便的工具。
**参数:**
- `prompt` (必填):图像的文字描述(最多4000个字符)
- `model` (可选): `glm-image` 或 `cogview-4-250304` (默认值: `glm-image`)
- `size` (可选):图像尺寸。, `1280x1280` (默认值: `1280x1280`)
- `quality` (可选): `hd` 或 `standard` (默认值: `hd` GLM图像)
- `user_id` (可选):用于防止滥用的最终用户ID(6-128个字符)
- `output` (可选): `base64` 或 `file_output` (默认值: `base64`)
- `file_output` (可选):保存图像文件的绝对路径(如果输出为 `file_output`)
- `poll_interval` (可选):轮询异步结果之间的等待秒数(默认值:3)
- `max_wait` (可选):等待生成的最长秒数(默认值:120)
**输出模式:**
- `base64`:直接以base64格式返回图像数据(如果>1MB,则自动切换到文件)
- `file_output`:将映像保存到指定路径的磁盘
**示例:**```
# Generate and get as base64
Generate a logo for my company and show me the image.
# Generate and save to file
Generate a logo and save it to /home/user/images/logo.png
行为:
- 对于GLM-Image:使用带有自动轮询的异步API直到完成
- 对于CogView-4:使用同步API
- 生成完成后自动下载结果
- 以base64格式返回图像或保存到指定路径
视频生成工具
7. list_video_models
列出所有可用的视频生成模型及其功能。```
Use this tool to discover available video models, their features, and supported parameters.
### 8. `generate_video`
从文本或图像异步生成视频。返回轮询的任务ID。
**参数:**
- `model` (必填):视频生成模型
- `cogvideox-3`:Z.AI旗舰机型(最高4K,5-10s,音频支持)
- `viduq1-text`:文本转视频,1080P,5秒
- `viduq1-image`:图像转视频,1080P,5秒
- `viduq1-start-end`:开始-结束帧,1080P,5秒
- `vidu2-image`:图像到视频,720P,4秒(更快,更便宜)
- `vidu2-start-end`:开始-结束帧,720P,4秒
- `vidu2-reference`:基于参考,720P,4秒
- `prompt` (可选):文本描述(最多512个字符)
- `image_url` (可选):用于图像到视频生成的图像URL
- `quality` (CogVideoX-3): `quality` 或 `speed`
- `size` (可选):视频分辨率
- `duration` (可选):视频持续时间(秒)
- `fps` (CogVideoX-3):30或60
- `with_audio` (可选):生成AI音效
- `style` (视频Q1文本): `general` 或 `anime`
- `aspect_ratio` (视频Q1/2): `16:9`, `9:16`,或 `1:1`
- `movement_amplitude` (视频): `auto`, `small`, `medium`,或 `large`
- `user_id` (可选):用于防止滥用的最终用户ID
**示例:**```
# Text-to-video
Generate a video of a cat playing with a ball.
# Image-to-video
Animate this image: [image_url]
# Start-end frame
Create a smooth transition from [first_frame] to [last_frame].
9. get_video_result
检索异步视频生成任务的结果。
参数:
task_id(必填):任务ID来自generate_video
> 注: 视频生成通常需要30秒到几分钟,具体取决于持续时间和质量。
10. generate_and_download_video ⭐ 推荐
生成视频并自动下载。轮询完成情况并保存视频文件。
参数:
- 所有参数来自
generate_video加上: file_output(可选):保存视频文件的绝对路径poll_interval(可选):轮询之间的等待秒数(默认值:10)max_wait(可选):最长等待秒数(默认值:300)
例子:```
Generate a video of a sunset over the ocean and save it to /home/user/videos/sunset.mp4
> **注:** 视频总是保存到文件中(对于base64来说太大)。视频URL将在1天后过期。
## 模型
### GLM图像
Z.AI的旗舰图像生成模型,采用混合自回归+扩散架构。
- **最适合**:复杂的构图、文字渲染、详细的插图、商业海报
- **质量选项**: `hd` (详细,约20s), `standard` (更快,~5-10秒)
- **尺寸范围**:每个维度1024-2048px(可被32整除)
- **推荐尺寸**: 1280×1280, 1568×1056, 1056×1568, 1472×1088, 1088×1472, 1728×960, 960×1728
- **异步支持**:是的
### CogView-4-250304
具有快速文本理解功能的通用图像生成。
- **最适合**:通用图像生成,快速迭代
- **质量选项**: `hd`, `standard`
- **尺寸范围**:每个维度512-2048px(可被16整除)
- **推荐尺寸**: 1024×1024, 768×1344, 864×1152, 1344×768, 1152×864, 1440×720, 720×1440
- **异步支持**:没有
______________________________________________________________________
## 视频模型
### CogVideoX-3
Z.AI的旗舰视频生成模型,具有改进的帧稳定性和清晰度。
- **最适合**:文本到视频、图像到视频、开始结束帧动画
- **决心**:高达4K(3840x2160)
- **持续时间**:5或10秒
- **特性**:音频生成,30/60 FPS,质量/速度模式
- **价格**:0.20美元/视频
### Q1视频
1080P输出的高质量视频生成。
|型号|性能|持续时间|价格|
|-------|------------|----------|-------|
| `viduq1-text` |文本转视频| 5秒| 0.40美元|
| `viduq1-image` |图像到视频|5s|0.40美元|
| `viduq1-start-end` |开始-结束帧|5s|0.40美元|
- **特性**:通用/动漫风格,运动幅度控制
### 视频2
具有720P输出的快速且经济高效的视频生成。
|型号|性能|持续时间|价格|
|-------|------------|----------|-------|
| `vidu2-image` |图像转视频| 4秒| 0.20美元|
| `vidu2-start-end` |开始-结束帧|4s|0.20美元|
| `vidu2-reference` |基于参考|4s|0.40美元|
- **特性**:音频生成、运动幅度控制、多图像参考
## 错误处理
服务器处理各种错误情况:
|错误类型|描述|
|-----------|-------------|
| `AUTH_ERROR` |API密钥无效或丢失|
| `RATE_LIMIT` |请求太多-将自动重试|
| `VALIDATION_ERROR` |无效参数|
| `SERVER_ERROR` |Z.AI服务器问题-将自动重试|
| `NETWORK_ERROR` |连接问题-将自动重试|
| `TIMEOUT_ERROR` |请求超时-将自动重试|
| `CONTENT_FILTER` |提示被内容策略阻止|
## 发展
### 设置```bash
git clone
cd z-ai-image-mcp
npm install
cp .env.example .env
# Edit .env with your API key
脚本```bash
npm run build # Build TypeScript
npm run dev # Run in development mode
npm test # Run all tests
npm run test:unit # Run unit tests only
npm run test:integration # Run integration tests
npm run test:e2e # Run E2E tests
npm run test:coverage # Run tests with coverage
npm run typecheck # Type check without emit
```
许可证
麻省理工学院
链接
- Z.AI文件
- MCP文件
- 获取API密钥
- GLM 编程计划
