jimeng_mcp_skill

Original source / Raw SKILL.md

---
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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/setup_guide.md

```markdown
# 即梦 MCP 服务器设置指南

即梦-mcp-server 的完整安装和配置指南。

## 目录

1. [前置条件](#前置条件)
2. [后端 API 设置](#后端-api-设置)
3. [MCP 服务器安装](#mcp-服务器安装)
4. [客户端配置](#客户端配置)
5. [验证](#验证)
6. [故障排除](#故障排除)

---

## 前置条件

### 系统要求

- **操作系统**：Ubuntu 20.04+ / macOS 12+ / Windows 10/11 (WSL2)
- **内存**：至少 4GB RAM
- **磁盘空间**：至少 10GB 可用空间
- **Python**：3.10 或更高版本
- **Docker**：最新版本
- **Git**：用于克隆仓库

### 检查前置条件

```bash
# 检查 Python 版本
python --version  # 应该是 3.10.x 或更高版本

# 检查 Docker
docker --version
docker-compose --version

# 检查 Git
git --version
```

---

## 后端 API 设置

jimeng-mcp-server 需要 jimeng-free-api-all 后端服务。

### 步骤 1：获取即梦 API 密钥

1. 访问 https://jimeng.jianying.com/
2. 登录您的账户
3. 打开浏览器开发者工具（F12）
4. 前往 Application > Cookies
5. 找到 `sessionid` 值 - 这就是您的 API 密钥
6. 复制 sessionid 值（格式：`Bearer <sessionid>`）

### 步骤 2：拉取 Docker 镜像

```bash
docker pull wwwzhouhui569/jimeng-free-api-all:latest
```

### 步骤 3：启动后端容器

```bash
docker run -it -d --init \
  --name jimeng-free-api-all \
  -p 8001:8000 \
  -e TZ=Asia/Shanghai \
  wwwzhouhui569/jimeng-free-api-all:latest
```

**端口说明：**
- 主机端口 8001 → 容器端口 8000
- 访问地址：http://localhost:8001

### 步骤 4：验证后端

```bash
# 检查容器是否运行
docker ps | grep jimeng

# 测试 API 端点
curl http://localhost:8001/health
```

预期响应：`{"status": "ok"}`

---

## MCP 服务器安装

### 步骤 1：克隆仓库

```bash
git clone https://github.com/wwwzhouhui/jimeng-mcp-server.git
cd jimeng-mcp-server
```

### 步骤 2：安装依赖

**方法 A：使用 uv（推荐）**

```bash
# 如果尚未安装，请先安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# 或在 Windows 上：.venv\Scripts\activate

# 安装依赖
uv pip install -e .
```

**方法 B：使用 pip**

```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或在 Windows 上：.venv\Scripts\activate

# 安装依赖
pip install -e .
```

### 步骤 3：配置环境

在项目根目录创建 `.env` 文件：

```bash
touch .env
```

编辑 `.env` 文件，填入您的配置：

```env
# 即梦 API 配置

# 您的即梦 API 密钥（必需）- 使用从 cookies 获取的 sessionid
JIMENG_API_KEY=your_sessionid_here

# API 基础 URL（可选，默认：https://jimeng.duckcloud.fun）
JIMENG_API_URL=http://127.0.0.1:8001

# 模型名称（可选，默认：jimeng-4.5）
JIMENG_MODEL=jimeng-4.5
```

**重要说明：**
- `JIMENG_API_KEY`：粘贴从即梦网站获取的 sessionid 值
- `JIMENG_API_URL`：本地后端使用 `http://127.0.0.1:8001`
- 不要在值周围添加引号

---

## 客户端配置

### Claude Desktop

**配置文件位置：**
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**：`~/.config/Claude/claude_desktop_config.json`

**stdio 模式（本地）：**

```json
{
  "mcpServers": {
    "jimeng": {
      "command": "python",
      "args": ["-m", "jimeng_mcp.server"],
      "env": {
        "JIMENG_API_KEY": "your_sessionid_here",
        "JIMENG_API_URL": "http://127.0.0.1:8001"
      }
    }
  }
}
```

**使用 .env 文件的替代方案：**

```json
{
  "mcpServers": {
    "jimeng": {
      "command": "python",
      "args": ["-m", "jimeng_mcp.server"]
    }
  }
}
```

如果使用此方法，请确保 `.env` 文件存在于项目目录中。

### Cherry Studio

**SSE 模式配置：**

1. 打开 Cherry Studio 设置
2. 导航到 MCP 服务器
3. 添加新服务器：
   - **名称**：Jimeng
   - **类型**：SSE
   - **URL**：`http://localhost:8080/sse`

**启动 SSE 服务器：**

```bash
cd jimeng-mcp-server
source .venv/bin/activate
python -m jimeng_mcp.server --transport sse --port 8080
```

### Cline / 其他 MCP 客户端

类似于 Claude Desktop 配置。根据您的客户端需要调整路径和环境变量。

---

## 验证

### 测试文本生成图像

在您的 MCP 客户端（Claude Desktop、Cherry Studio 等）中：

```
生成一张图片：樱花树下的柴犬
```

或

```
Generate an image: a cute dog under cherry blossom tree
```

**预期行为：**
1. 客户端识别请求
2. 调用 jimeng-mcp-server 的 `text_to_image` 工具
3. 返回图片 URL
4. 可以查看/下载图片

### 测试图像合成

```
合成这两张图片：
- 图片1: [URL]
- 图片2: [URL]
创建无缝融合效果
```

### 测试文本生成视频

```
创建一个视频：小猫在钓鱼
```

**注意**：视频生成需要 30-60 秒。

### 测试图像生成视频

```
为这张图片添加动画效果：[image URL]
添加轻柔的运动和镜头缩放
```

---

## 故障排除

### 问题："服务器无响应"

**症状：**
- 连接被拒绝错误
- 调用工具时超时

**解决方案：**

1. 检查后端容器状态：
   ```bash
   docker ps | grep jimeng
   ```

2. 如果未运行，重启后端：
   ```bash
   docker restart jimeng-free-api-all
   ```

3. 验证端口可访问性：
   ```bash
   curl http://localhost:8001/health
   ```

4. 检查防火墙设置

### 问题："API 密钥无效"

**症状：**
- 身份验证错误
- "未授权"响应

**解决方案：**

1. 从即梦网站获取新的 sessionid：
   - 登录到 https://jimeng.jianying.com/
   - F12 > Application > Cookies > sessionid
   - 复制新值

2. 更新 `.env` 文件：
   ```env
   JIMENG_API_KEY=new_sessionid_value
   ```

3. 重启 MCP 服务器

### 问题："生成失败"

**症状：**
- 工具返回错误
- 没有生成图片/视频

**解决方案：**

1. 检查后端日志：
   ```bash
   docker logs jimeng-free-api-all
   ```

2. 验证提示词不为空

3. 检查到即梦 API 的网络连接

4. 先尝试更简单的提示词

5. 确保有足够的 API 积分（免费层每天 66 积分）

### 问题："生成超时"

**症状：**
- 请求时间过长
- 60+ 秒后仍无响应

**解决方案：**

1. 对于视频，最多等待 90 秒
2. 尝试较低分辨率（720p 而非 1080p）
3. 检查服务器资源使用情况：
   ```bash
   docker stats jimeng-free-api-all
   ```
4. 如果 CPU/内存占用高，重启后端

### 问题："模块未找到"

**症状：**
- Python 导入错误
- "No module named 'jimeng_mcp'"

**解决方案：**

1. 确保虚拟环境已激活：
   ```bash
   source .venv/bin/activate  # Linux/macOS
   .venv\Scripts\activate     # Windows
   ```

2. 重新安装依赖：
   ```bash
   pip install -e .
   ```

3. 验证 Python 版本：
   ```bash
   python --version  # 必须是 3.10+
   ```

---

## 高级配置

### 运行多个实例

要运行多个 jimeng-mcp-server 实例：

1. **为后端使用不同端口：**
   ```bash
   docker run -d -p 8001:8000 --name jimeng-api-1 ...
   docker run -d -p 8002:8000 --name jimeng-api-2 ...
   ```

2. **配置不同的 MCP 服务器：**
   ```json
   {
     "mcpServers": {
       "jimeng-1": {
         "command": "python",
         "args": ["-m", "jimeng_mcp.server"],
         "env": {"JIMENG_API_URL": "http://127.0.0.1:8001"}
       },
       "jimeng-2": {
         "command": "python",
         "args": ["-m", "jimeng_mcp.server"],
         "env": {"JIMENG_API_URL": "http://127.0.0.1:8002"}
       }
     }
   }
   ```

### 自定义 API 端点

如果使用托管的 jimeng-free-api-all 实例：

```env
JIMENG_API_URL=https://your-domain.com
JIMENG_API_KEY=your_api_key
```

### 日志配置

启用调试日志：

```env
LOG_LEVEL=DEBUG
```

查看日志：
```bash
# 对于 stdio 模式：查看客户端日志
# 对于 SSE 模式：查看服务器控制台输出
```

---

## 安全最佳实践

1. **永远不要将 .env 文件提交到版本控制**
   - 将 `.env` 添加到 `.gitignore`

2. **保护 API 密钥**
   - 不要公开分享 sessionid
   - 如果泄露请重新生成

3. **限制网络暴露**
   - 尽可能使用 localhost (127.0.0.1)
   - 不要公开暴露 Docker 端口

4. **保持依赖更新**
   ```bash
   pip install --upgrade jimeng-mcp-server
   ```

5. **监控使用情况**
   - 跟踪 API 积分消耗
   - 为配额限制设置警报

---

## 卸载

### 移除 MCP 服务器

```bash
# 停用虚拟环境
deactivate

# 移除项目目录
rm -rf jimeng-mcp-server
```

### 停止后端

```bash
# 停止并移除容器
docker stop jimeng-free-api-all
docker rm jimeng-free-api-all

# 移除镜像（可选）
docker rmi wwwzhouhui569/jimeng-free-api-all:latest
```

### 移除客户端配置

编辑 MCP 客户端配置文件，移除 jimeng 服务器条目。

---

## 获取帮助

- **GitHub 问题**：https://github.com/wwwzhouhui/jimeng-mcp-server/issues
- **文档**：查看项目 README 和 API 参考
- **社区**：查看讨论或论坛

---

## 更新日志

### 最新更新

查看 GitHub 发布页面了解版本历史和变更：
https://github.com/wwwzhouhui/jimeng-mcp-server/releases

---

**最后更新**：2025-12-14
**版本**：2.0

```