# 二次元美图生成器

基于火山方舟 ARK `doubao-seedream` 与 Agnes Image 2.1 Flash 的二次元/CG 高质量图片生成工具，支持文生图、图生图、多图生图、组图生成（仅 ARK），内置 16 种风格预设，支持风格一致性管理，同时提供 Web UI 和 MCP 服务器两种使用方式。

## 特性

- **双引擎支持** - 火山方舟 ARK (doubao-seedream) + Agnes Image 2.1 Flash
- **文生图** - 文本提示词 -> 单张高质量二次元美图
- **图生图** - 单张参考图 + 文本 -> 单张图片（保持姿势/构图，改变风格/内容）
- **多图生图** - 2-14 张参考图 + 文本 -> 单张图片
- **组图生成**（ARK） - 生成一组内容关联的图片（sequential_image_generation: auto）
- **宽高比控制**（Agnes） - 1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9
- **16 种风格预设** - CG厚涂、唯美水彩、赛博朋克、新海诚光影、古风国潮、暗黑哥特、概念艺术等
- **风格一致性** - 通过风格配置文件确保多张图片风格统一
- **智能提示词引擎** - 自动组合用户提示词 + 风格后缀 + 构图 + 光线 + 质量增强词
- **Web UI** - 暗色主题，支持拖拽上传参考图、引擎切换、模式切换、组图展示
- **MCP 服务器** - 14 个工具，供 AI 智能体调用全部生成能力
- **REST API** - 完整的 RESTful API

## 快速开始

### 1. 安装依赖

```bash
cd D:\projects\image_MCP
pip install -r requirements.txt
```

### 2. 配置 API Key

```bash
copy .env.example .env
```

编辑 `.env` 文件：

```env
# Agent Plan API（文生图 + 图生图 + 组图，doubao-seedream-5.0-lite 全部支持）
AGENT_API_KEY=your_agent_api_key_here

# 标准 API（可选，图生图/组图时使用更强的 pro 模型）
ARK_API_KEY=your_standard_api_key_here

# Agnes Image（可选，文生图/图生图，支持宽高比）
AGNES_API_KEY=your_agnes_api_key_here
```

- Agent Plan API Key: https://console.volcengine.com/ark/region:cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan
- 标准 API Key（可选）: https://console.volcengine.com/ark/region:cn-beijing/apikey
- Agnes API Key: https://apihub.agnes-ai.com/

> **只需 `AGENT_API_KEY` 即可使用全部 ARK 功能**：文生图、图生图、多图生图、组图生成（`doubao-seedream-5.0-lite` 全部支持）。配置 `ARK_API_KEY` 后，图生图/组图会自动切换到更强的 `doubao-seedream-5-0-pro-260628` 模型。Agnes 为可选的第二引擎。

### 3. 启动 Web 服务

```bash
python main.py
```

访问 http://127.0.0.1:8765

### 4. 启动 MCP 服务器

```bash
python mcp_server.py
```

## MCP 配置

### opencode

```json
{
  "mcp": {
    "anime-image-mcp": {
      "type": "local",
      "command": ["python", "D:/projects/image_MCP/mcp_server.py"]
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "anime-image-mcp": {
      "command": "python",
      "args": ["D:/projects/image_MCP/mcp_server.py"]
    }
  }
}
```

## MCP 工具列表

| 工具名 | 描述 |
|--------|------|
| `generate_anime_image` | 生成单张图片（文生图/图生图/多图生图，支持 ark/agnes） |
| `generate_sequence` | 生成一组内容关联的组图（仅 ARK） |
| `generate_batch` | 批量生成多张独立图片 |
| `generate_with_profile` | 使用风格配置文件生成（保持风格一致性） |
| `list_styles` | 列出所有风格预设 |
| `get_style_detail` | 获取风格预设详情 |
| `list_compositions` | 列出构图预设 |
| `list_lightings` | 列出光线预设 |
| `list_providers` | 列出可用生成引擎（ark/agnes） |
| `list_ratios` | 列出宽高比预设（Agnes） |
| `create_style_profile` | 创建风格配置文件 |
| `preview_prompt` | 预览完整提示词 |
| `get_history` | 获取生成历史 |
| `get_image_info` | 获取指定图片信息 |

## 生成引擎说明

| 引擎 | 模型 | 支持功能 | 尺寸 | 宽高比 |
|------|------|----------|------|--------|
| **ARK** | doubao-seedream-5.0-lite / 5.0-pro | 文生图、图生图、多图生图、组图生成、水印、格式选择 | 1K / 2K / 4K | 无 |
| **Agnes** | agnes-image-2.1-flash | 文生图、图生图、高信息密度优化 | 1K / 2K / 3K / 4K | 1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9 |

## 生成模式说明

| 模式 | 参考图 | sequential_image_generation | 输出 | 说明 |
|------|--------|---------------------------|------|------|
| 文生图 | 无 | disabled | 单张 | 文本 -> 图片 |
| 单图生图 | 1张 | disabled | 单张 | 参考图+文本 -> 图片 |
| 多图生图 | 2-14张 | disabled | 单张 | 多参考图+文本 -> 图片 |
| 文生组图 | 无 | auto | 多张(≤15) | 文本 -> 一组关联图片 |
| 单图生组图 | 1张 | auto | 多张(≤14) | 参考图+文本 -> 一组关联图片 |
| 多图生组图 | 2-14张 | auto | 多张(≤15-参考图数) | 多参考图+文本 -> 一组关联图片 |

## 风格预设

| ID | 名称 | 分类 |
|----|------|------|
| `cg_thick_paint` | CG厚涂 | CG数字绘画 |
| `watercolor_dream` | 唯美水彩 | 艺术质感 |
| `cyberpunk_neon` | 赛博朋克 | 场景氛围 |
| `fantasy_epic` | 幻想史诗CG | CG数字绘画 |
| `anime_fresh` | 日系清新 | 动漫风格 |
| `dark_gothic` | 暗黑哥特 | 特殊风格 |
| `oil_classical` | 古典油画 | 艺术质感 |
| `shinkai_style` | 新海诚光影 | 动漫风格 |
| `concept_art` | 概念艺术 | CG数字绘画 |
| `chinese_guochao` | 古风国潮 | 特殊风格 |
| `cel_shading` | 赛璐璐动画 | 动漫风格 |
| `pastel_soft` | 粉彩柔光 | 艺术质感 |
| `dark_fantasy` | 暗黑幻想 | CG数字绘画 |
| `chibi_cute` | Q版萌系 | 动漫风格 |
| `ukiyo_modern` | 浮世绘现代 | 艺术质感 |
| `studio_portrait` | 影棚肖像 | CG数字绘画 |

## REST API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/styles` | 获取风格预设列表 |
| GET | `/api/styles/{id}` | 获取风格详情 |
| GET | `/api/compositions` | 获取构图预设 |
| GET | `/api/lightings` | 获取光线预设 |
| POST | `/api/generate` | 生成单张图片（支持参考图） |
| POST | `/api/generate/sequence` | 生成组图 |
| POST | `/api/generate/batch` | 批量生成 |
| POST | `/api/generate/profile` | 使用风格配置文件生成 |
| POST | `/api/profile/create` | 创建风格配置文件 |
| POST | `/api/preview-prompt` | 预览完整提示词 |
| POST | `/api/upload` | 上传参考图片 |
| GET | `/api/history` | 获取历史记录 |
| GET | `/api/history/{id}` | 获取指定记录 |
| DELETE | `/api/history/{id}` | 删除指定记录 |
| DELETE | `/api/history` | 清空历史 |
| GET | `/api/images/{filename}` | 获取图片文件 |
| GET | `/api/uploads/{filename}` | 获取上传的参考图 |

API 文档：http://127.0.0.1:8765/docs

## 项目结构

```
image_MCP/
├── main.py              # FastAPI Web 服务入口
├── mcp_server.py        # MCP 服务器入口
├── config.py            # 配置管理（双 API 支持）
├── prompt_styles.py     # 提示词引擎（16种风格预设）
├── image_generator.py   # 核心生成器（文生图/图生图/组图）
├── requirements.txt
├── .env.example
├── static/              # Web UI
│   ├── index.html
│   ├── style.css
│   └── app.js
├── output/              # 生成图片存储
│   └── uploads/         # 上传的参考图
└── data/
    └── history.json
```

## 使用示例

### Python - 图生图

```python
from image_generator import get_generator

gen = get_generator()
result = gen.generate(
    user_prompt="保持姿势不变，将服装材质改为透明清水",
    style_id="cg_thick_paint",
    reference_images="https://example.com/ref.png",
)
print(f"图片已保存: {result.local_path}")
```

### Python - 组图生成

```python
from image_generator import get_generator

gen = get_generator()
results = gen.generate_sequence(
    user_prompt="生成3张女孩在游乐园的图片，涵盖早晨、中午、晚上",
    style_id="anime_fresh",
    max_images=3,
    reference_images=["https://example.com/ref1.png", "https://example.com/ref2.png"],
)
for r in results:
    print(f"图片 {r.sequence_index + 1}/{r.sequence_total}: {r.local_path}")
```

### Python - Agnes 引擎

```python
from image_generator import get_generator
from prompt_styles import PROVIDER_AGNES

gen = get_generator()

# 文生图（16:9 宽屏）
result = gen.generate(
    user_prompt="日出时分薄雾峡谷上方的发光浮空城市，电影级写实风格，广角构图",
    provider=PROVIDER_AGNES,
    size="2K",
    ratio="16:9",
)
print(f"图片已保存: {result.local_path}")

# 图生图（构图保留）
result = gen.generate(
    user_prompt="将场景改为赛博朋克夜景，保留原始构图",
    provider=PROVIDER_AGNES,
    reference_images="https://example.com/input.png",
    size="2K",
    ratio="3:4",
)
print(f"图片已保存: {result.local_path}")
```

### cURL - 组图生成

```bash
curl -X POST http://127.0.0.1:8765/api/generate/sequence \
  -H "Content-Type: application/json" \
  -d '{"user_prompt": "生成3张猫咪在不同场景的图片", "max_images": 3, "style_id": "pastel_soft"}'
```

## 技术栈

- **后端**: Python + FastAPI + Uvicorn
- **AI 模型**: 火山方舟 ARK doubao-seedream + Agnes Image 2.1 Flash
- **MCP**: 纯 Python 实现 JSON-RPC 2.0 (无需 mcp 包)
- **前端**: 原生 HTML/CSS/JS

## 环境要求

- Python 3.10+
- 至少配置以下 API Key 之一：
  - 火山方舟 ARK (Agent Plan 或标准 API)
  - Agnes Image API Key (https://apihub.agnes-ai.com/)