xiaohuihui-tech-article skill

---
name: jimeng_mcp_skill
description: 使用jimeng-mcp-server进行AI图像和视频生成。当用户请求从文本生成图像、合成多张图片、从文本描述创建视频或为静态图像添加动画时使用此技能。支持四大核心能力：文生图、图像合成、文生视频、图生视频。需要jimeng-mcp-server在本地运行或通过SSE/HTTP访问。
---

# 即梦 AI 生成技能

## 概述

即梦技能通过 jimeng-mcp-server 实现 AI 驱动的图像和视频生成，这是一个集成了即梦 AI 多模态生成能力的 MCP（模型上下文协议）服务器。使用此技能可以直接通过自然语言指令创建视觉内容。

**核心能力：**
- 🎨 **文本生成图像**：从文本描述生成高质量图像
- 🎭 **图像合成**：智能合并和融合多张图片
- 🎬 **文本生成视频**：从文本提示创建短视频
- 🎞️ **图像生成视频**：为静态图像添加动画效果

**何时使用此技能：**
- 用户要求生成、创建或制作图像或视频
- 用户提到"jimeng"、"即梦"或请求AI视觉内容生成
- 用户提供文本描述并希望得到视觉输出
- 用户想要组合、合并或合成多张图片
- 用户想为静态图像添加动画或运动效果

## 前置条件

使用此技能前，请确保 jimeng-mcp-server 已正确配置：

1. **服务器必须运行**，通过以下模式之一：
   - **stdio 模式**：在 MCP 客户端（Claude Desktop、Cherry Studio）中配置
   - **SSE 模式**：作为带 SSE 传输的 HTTP 服务器运行
   - **HTTP 模式**：作为 REST API 服务器运行

2. **环境变量已配置**：
   - `JIMENG_API_KEY`：您的即梦 API 密钥（从即梦网站 cookies 获取）
   - `JIMENG_API_URL`：API 端点（默认：http://127.0.0.1:8001）
   - `JIMENG_MODEL`：模型名称（默认：jimeng-4.5）

3. **后端 API 运行中**：jimeng-free-api-all Docker 容器必须处于活动状态

详细的设置说明请参考 `references/setup_guide.md`。

## 快速开始

### 基本使用模式

当用户请求图像或视频生成时，遵循以下工作流程：

1. **识别任务类型**，基于用户输入
2. **提取必需参数**，从请求中获取
3. **调用相应的 jimeng-mcp-server 工具**
4. **返回生成的内容 URL** 给用户

### 示例请求

**文本生成图像：**
```
用户："用即梦生成一张图片：樱花树下的柴犬"
→ 使用 text_to_image 工具，参数 prompt="樱花树下的柴犬"
```

**图像合成：**
```
用户："帮我合成这两张图片，风格偏向第一张"
→ 使用 image_composition 工具，提供图片 URL
```

**文本生成视频：**
```
用户："创建一个5秒视频：小马过河的故事场景"
→ 使用 text_to_video 工具，设置提示词和时长
```

**图像生成视频：**
```
用户："为这张图片添加动画效果"
→ 使用 image_to_video 工具，提供图片 URL
```

## 核心能力

### 1. 文本生成图像

使用即梦 4.5 引擎从文本描述生成图像。

**工具**：`text_to_image`

**参数：**
- `prompt`（必需）：期望图像的文本描述
- `model`（可选）：模型版本（默认：jimeng-4.5）
- `ratio`（可选）：图像宽高比（"1:1", "4:3", "3:4", "16:9", "9:16"）
- `resolution`（可选）：分辨率预设（"1k", "2k", "4k"，默认：2k）
- `negativePrompt`（可选）：要在生成图像中避免的元素

**常见宽高比：**
- 16:9 → 横向/宽屏（视频封面、Banner）
- 1:1 → 正方形（头像、社交媒体）
- 9:16 → 竖向/手机屏幕（短视频封面）
- 4:3 → 标准横向（博客配图）
- 3:4 → 标准竖向（人像照片）

**使用示例：**
```python
# 用户请求："生成一张图片：夕阳下的海滩，有椰子树"
{
  "model": "jimeng-4.5",
  "prompt": "夕阳下的海滩，有椰子树",
  "ratio": "16:9",
  "resolution": "2k"
}
```

**返回结果：**
返回包含多张图片 URL 的数组，可显示或下载。

**提示：**
- 更高分辨率（4k）适合印刷品和高质量展示
- 较低分辨率（1k）适合快速预览
- 使用描述性提示词以获得更好的结果
- 指定艺术风格、光照、氛围以增强控制

### 2. 图像合成

通过智能融合合并和混合多张图片。

**工具**：`image_composition`

**参数：**
- `prompt`（必需）：如何合成图片的描述
- `images`（必需）：要合成的 2-5 个图片 URL 数组
- `model`（可选）：模型版本（默认：jimeng-4.5）
- `ratio`（可选）：输出图像宽高比（"1:1", "4:3", "3:4", "16:9", "9:16"）
- `resolution`（可选）：分辨率预设（"1k", "2k", "4k"，默认：2k）

**使用示例：**
```python
# 用户请求："合成这两张图，保留第一张的风格"
{
  "model": "jimeng-4.5",
  "prompt": "将两张图片无缝融合，保持第一张图片的艺术风格",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "ratio": "4:3",
  "resolution": "2k"
}
```

**使用场景：**
- 将人像与背景融合
- 图片之间的风格迁移
- 创建艺术合成作品
- 合并多张照片的元素

**提示：**
- 在提示词中提供清晰的合成说明
- 图片应具有兼容的分辨率
- 描述期望的混合风格（无缝、艺术、真实）

### 3. 文本生成视频

从文本描述创建短视频。

**工具**：`text_to_video`

**参数：**
- `prompt`（必需）：视频场景的文本描述
- `model`（可选）：模型版本（默认：jimeng-video-3.0）
- `ratio`（可选）：视频宽高比（"16:9", "9:16", "4:3", "3:4", "1:1"）
- `resolution`（可选）：预设分辨率（"480p", "720p", "1080p"）

**分辨率预设：**
- "480p" → 快速预览
- "720p" → 平衡质量/速度（推荐）
- "1080p" → 高质量

**使用示例：**
```python
# 用户请求："生成5秒视频：小猫在钓鱼"
{
  "model": "jimeng-video-3.0",
  "prompt": "一只橘色小猫坐在河边，手持鱼竿专注地钓鱼，阳光明媚",
  "ratio": "16:9",
  "resolution": "720p"
}
```

**视频特性：**
- 时长：通常 3-5 秒
- 格式：MP4
- 生成时间：30-60 秒
- 帧率：24-30 fps

**提示：**
- 包含场景细节、动作和氛围
- 保持提示词专注于单一清晰的动作
- 指定一天中的时间、天气或情绪以获得更好的结果
- 从 720p 开始以平衡质量和速度

### 4. 图像生成视频动画

为静态图像添加运动和动画效果。

**工具**：`image_to_video`

**参数：**
- `prompt`（必需）：期望动画效果的描述
- `file_paths`（必需）：要添加动画的图片 URL 数组
- `model`（可选）：模型版本（默认：jimeng-video-3.0）
- `ratio`（可选）：视频宽高比（"16:9", "9:16", "4:3", "3:4", "1:1"）
- `resolution`（可选）：预设分辨率（"480p", "720p", "1080p"）

**使用示例：**
```python
# 用户请求："让这张照片动起来，添加轻柔的镜头缩放"
{
  "model": "jimeng-video-3.0",
  "prompt": "添加轻柔的运动效果和自然的镜头缩放，营造电影感",
  "file_paths": ["https://example.com/photo.jpg"],
  "ratio": "16:9",
  "resolution": "720p"
}
```

**动画类型：**
- 人物动作（Character motion）
- 镜头运动（Camera movements）
- 场景转换（Scene transitions）
- 环境效果（Environmental effects：风、雨等）

**提示：**
- 描述期望的运动类型
- 选择效果时考虑图像内容
- 人像照片适合细微的动作
- 风景照片适合平移/缩放效果

## 工作流程指南

### 决策树

```
收到用户请求
    │
    ├─ 包含"生成图片"或"create image"？
    │   └─ 是 → 使用 text_to_image
    │
    ├─ 包含"合成"或"merge/blend images"？
    │   └─ 是 → 使用 image_composition
    │
    ├─ 包含"生成视频"或"create video"？
    │   └─ 是 → 使用 text_to_video
    │
    └─ 包含"动画"或"animate image"？
        └─ 是 → 使用 image_to_video
```

### 参数提取

处理用户请求时：

1. **提取提示词**：用户对期望内容的描述
2. **识别宽高比**：提取尺寸偏好（横向/竖向/正方形）对应 ratio 参数
3. **解析分辨率需求**：寻找质量要求，对应 resolution 参数
4. **收集图片 URL**：用于合成和动画任务

### 错误处理

如果工具执行失败：

1. **检查服务器状态**：验证 jimeng-mcp-server 是否运行
2. **验证 API 密钥**：确保 JIMENG_API_KEY 已配置
3. **检查参数**：确认所有必需字段已提供
4. **检查图片 URL**：验证合成/动画的 URL 是否可访问
5. **清晰报告错误**：解释问题并建议解决方案

常见错误：
- `API key not configured`：在环境中设置 JIMENG_API_KEY
- `Server not responding`：启动 jimeng-free-api-all Docker 容器
- `Invalid image URL`：确保 URL 公开可访问
- `Generation timeout`：大型视频可能需要 60+ 秒

## 高级用法

### 组合多个工具

对于复杂的创意任务，可以链式使用工具：

**示例：创建动画艺术作品**
1. 使用 `text_to_image` 生成基础图像
2. 使用 `image_to_video` 为结果添加动画

**示例：合成和优化**
1. 使用 `image_composition` 合成图片
2. 使用调整后的提示词生成变体

### 优化技巧

**加快生成速度：**
- 使用较低分辨率（720p 而非 1080p，或 1k 而非 2k）
- 保持提示词简洁但具有描述性

**提高质量：**
- 使用详细、具体的提示词
- 根据场景选择合适的 ratio（宽高比）
- 使用更高的 resolution（2k 或 4k）
- 指定艺术风格和技术
- 包含光照和氛围描述

### 批量处理

当用户请求多次生成时：

1. 按顺序处理请求（一次一个）
2. 为每个项目提供进度更新
3. 在最终响应前收集所有结果
4. 考虑资源限制（API 配额）

## 故障排除

### 服务器连接问题

**症状**：工具返回连接错误

**解决方案：**
1. 检查 jimeng-free-api-all Docker 容器是否运行：
   ```bash
   docker ps | grep jimeng
   ```
2. 验证服务器是否可访问：
   ```bash
   curl http://127.0.0.1:8001/health
   ```
3. 如有需要重启 Docker 容器

### API 密钥问题

**症状**："Invalid API key"或身份验证错误

**解决方案：**
1. 验证 .env 文件中的 JIMENG_API_KEY
2. 从即梦网站 cookies 获取新的 API 密钥（sessionid 值）
3. 确保密钥格式正确（无额外空格或引号）

### 生成质量问题

**症状**：质量差或意外结果

**解决方案：**
1. 使用更具体的细节优化提示词
2. 调整 `ratio` 参数选择合适的宽高比
3. 尝试不同的 `resolution` 分辨率
4. 添加 `negativePrompt` 以排除不需要的元素

### 超时错误

**症状**：生成时间过长或超时

**解决方案：**
1. 视频生成通常需要 30-60 秒 - 请耐心等待
2. 如果持续超时，尝试较低分辨率
3. 检查服务器资源使用情况
4. 验证到即梦 API 的网络连接

## 资源

### references/

- `setup_guide.md`：详细的安装和配置说明
- `api_reference.md`：所有工具的完整 API 文档

### 项目链接

- **GitHub 仓库**：https://github.com/wwwzhouhui/jimeng-mcp-server
- **后端 API**：https://github.com/wwwzhouhui/jimeng-free-api-all
- **即梦官网**：https://jimeng.jianying.com/

## 最佳实践

1. **始终在尝试生成前验证服务器状态**
2. **根据用例和速度要求使用适当的分辨率**（ratio 控制比例，resolution 控制清晰度）
3. **提供详细的提示词**以获得更好的生成质量
4. **优雅地处理错误**并提供清晰的用户反馈
5. **处理多个请求时考虑速率限制**
6. **在复杂合成前先用简单提示词测试**
7. **缓存常用参数**，如首选 ratio 和 resolution

## 限制

- **免费层限制**：官方即梦 API 每天 66 积分
- **视频时长**：通常限制为 3-10 秒
- **生成时间**：视频可能需要 30-60 秒生成
- **图像合成**：2-3 张图片效果最佳，最多支持 5 张
- **服务器依赖**：需要 jimeng-free-api-all 后端运行
- **网络要求**：必须有互联网访问以调用即梦 API