341 lines
9.5 KiB
Markdown
341 lines
9.5 KiB
Markdown
# API 参考
|
||
|
||
ComfyUI-AnimaTool 提供三种 API 接入方式：
|
||
|
||
1. **MCP Server** - Cursor/Claude 原生图片显示
|
||
2. **ComfyUI HTTP API** - 随 ComfyUI 启动
|
||
3. **独立 FastAPI Server** - 可独立部署
|
||
|
||
## MCP Tools
|
||
|
||
### generate_anima_image
|
||
|
||
生成二次元/插画图片。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `prompt_hint` | string | 否 | - | 人类可读的需求摘要 |
|
||
| `aspect_ratio` | string | 否 | - | 长宽比（如 `16:9`、`9:16`） |
|
||
| `width` | integer | 否 | - | 宽度（像素，16 的倍数，会覆盖 aspect_ratio） |
|
||
| `height` | integer | 否 | - | 高度（像素，16 的倍数，会覆盖 aspect_ratio） |
|
||
| `quality_meta_year_safe` | string | **是** | - | 质量/年份/安全标签（必须含 safe/sensitive/nsfw/explicit） |
|
||
| `count` | string | **是** | - | 人数（`1girl`、`2girls`、`1boy`） |
|
||
| `character` | string | 否 | `""` | 角色名 |
|
||
| `series` | string | 否 | `""` | 作品名 |
|
||
| `appearance` | string | 否 | `""` | 外观描述（发色、眼睛等） |
|
||
| `artist` | string | **是** | - | 画师（必须带 `@`，如 `@fkey`） |
|
||
| `style` | string | 否 | `""` | 画风 |
|
||
| `tags` | string | **是** | - | Danbooru 标签（逗号分隔） |
|
||
| `nltags` | string | 否 | `""` | 自然语言补充 |
|
||
| `environment` | string | 否 | `""` | 环境/光影 |
|
||
| `neg` | string | **是** | - | 负面提示词 |
|
||
| `steps` | integer | 否 | 25 | 步数 |
|
||
| `cfg` | number | 否 | 4.5 | CFG |
|
||
| `sampler_name` | string | 否 | `er_sde` | 采样器 |
|
||
| `seed` | integer | 否 | 随机 | 种子 |
|
||
| `repeat` | integer | 否 | 1 | 提交几次独立生成任务（queue 模式，每次独立随机 seed）。范围 1-16 |
|
||
| `batch_size` | integer | 否 | 1 | 单次任务内生成几张（latent batch，更吃显存）。范围 1-4 |
|
||
| `loras` | array | 否 | `[]` | 追加 LoRA（仅 UNET）。每项 `{"name": "...", "weight": 1.0}`，name 必须与 `/models/loras` 返回值一致 |
|
||
|
||
> 总生成张数 = `repeat` × `batch_size`。推荐使用 `repeat`（默认方式，显存友好）。
|
||
|
||
#### 返回
|
||
|
||
MCP Server 返回：
|
||
- `ImageContent`: 图片（base64 编码，原生显示）
|
||
- `TextContent`: 历史记录提示（如 `已保存为历史记录 #12。可用 reroll_anima_image(source="last") 重新生成。`）
|
||
|
||
---
|
||
|
||
### list_anima_models
|
||
|
||
查询 ComfyUI 当前可用的模型文件列表。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `model_type` | string | **是** | `loras` / `diffusion_models` / `vae` / `text_encoders` |
|
||
|
||
> 当 `model_type=loras` 时，强制只返回存在同名 `.json` sidecar 元数据文件的 LoRA。
|
||
|
||
#### 返回
|
||
|
||
`TextContent`：JSON 格式的模型列表。
|
||
|
||
---
|
||
|
||
### list_anima_history
|
||
|
||
查看最近的图片生成历史记录。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `limit` | integer | 否 | 5 | 返回最近几条（1-50） |
|
||
|
||
#### 返回
|
||
|
||
`TextContent`：每行一条记录摘要，格式：
|
||
|
||
```
|
||
#12 [2026-02-06 17:30] @fkey | 1girl, white hair, blue eyes | seed:42 | 872x1160
|
||
#11 [2026-02-06 17:28] @ciloranko | 2girls, school uniform | seed:78923 | 1024x1024
|
||
```
|
||
|
||
---
|
||
|
||
### reroll_anima_image
|
||
|
||
基于历史记录重新生成图片。引用一条历史记录作为基础参数，可选覆盖部分参数。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `source` | string | **是** | `"last"`（最近一条）或历史 ID（如 `"12"` 或 `"#12"`） |
|
||
| *其他* | - | 否 | 所有 `generate_anima_image` 的参数均可作为覆盖项 |
|
||
|
||
> - `seed` 默认自动随机（出不同画面）。手动指定 seed 可复现相同画面。
|
||
> - `repeat` 同样可用，如 `reroll_anima_image(source="last", repeat=3)` 一次出 3 张。
|
||
|
||
#### 典型用法
|
||
|
||
| 场景 | 调用 |
|
||
|------|------|
|
||
| 再 roll 一次 | `reroll_anima_image(source="last")` |
|
||
| 再来 3 张 | `reroll_anima_image(source="last", repeat=3)` |
|
||
| 换个画师再来 | `reroll_anima_image(source="last", artist="@ciloranko")` |
|
||
| 回溯第 3 条记录 | `reroll_anima_image(source="3")` |
|
||
| 保持 seed 不变加 LoRA | `reroll_anima_image(source="last", seed=原seed, loras=[...])` |
|
||
|
||
#### 返回
|
||
|
||
与 `generate_anima_image` 一致（图片 + 历史记录提示）。
|
||
|
||
---
|
||
|
||
### generate_qwen_image
|
||
|
||
使用 QwenEdit 引擎生成/编辑图片，支持自然语言、0参考文生图、局部修图换装。
|
||
|
||
#### 参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `character_and_action` | string | 【生图必填】角色与主要动作的描述。局部修改时若不改动作请留空。 |
|
||
| `appearance_details` | string | 【生图必填】角色的外貌与服装细节。修图时如需强制锚定特征填入此处，否则留空。 |
|
||
| `environment_and_lighting`| string | 【生图必填】背景环境、光影描述。修图时若不改背景必须留空。 |
|
||
| `style_and_quality` | string | 【全局选填】画质词或整体画风（如 '8k，电影级光影'）。 |
|
||
| `edit_actions` | array | 【修图必填】局部修改指令数组。纯生图**必须留空**。 |
|
||
| `preserve_constraints`| string | 【修图核心锁】强制防崩坏指令，如 '保持人物脸部特征和背景不变'。 |
|
||
| `render_text` | string | 【选填】需要 Qwen 在画面中精准生成的文字。 |
|
||
| `base_image` | string | 【选填】底图/原图的**本地绝对路径**（⚠️受MCP限制必须是绝对路径。独立 PyPI 包暂不支持 QwenEdit）。传入后切换为图生图模式（Picture 1）。 |
|
||
| `reference_images` | array | 【选填】参考图**本地绝对路径**数组（最多2张）。依次映射为 Picture 2, Picture 3。 |
|
||
| `aspect_ratio` | string | 【选填】生图/扩图长宽比（如 '16:9'）。有底图时默认跟随原图比例。 |
|
||
| `seed` | integer | 【选填】随机种子。 |
|
||
| `repeat` | integer | 【选填】独立任务重复次数，每次随机 seed。 |
|
||
|
||
#### 返回
|
||
|
||
MCP Server 返回：
|
||
- `ImageContent`: 图片（原生显示）
|
||
- `TextContent`: 保存路径与 Qwen 最终发送的指令。
|
||
|
||
---
|
||
|
||
## ComfyUI HTTP API
|
||
|
||
随 ComfyUI 启动自动注册以下路由。
|
||
|
||
### GET /anima/health
|
||
|
||
健康检查。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"comfyui_url": "http://127.0.0.1:8188",
|
||
"tool_root": "/path/to/ComfyUI-AnimaTool"
|
||
}
|
||
```
|
||
|
||
### GET /anima/schema
|
||
|
||
获取 Tool Schema（JSON Schema 格式）。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"name": "generate_anima_image",
|
||
"description": "...",
|
||
"parameters": { ... }
|
||
}
|
||
```
|
||
|
||
### GET /anima/knowledge
|
||
|
||
获取专家知识库。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"anima_expert": "...",
|
||
"artist_list": "...",
|
||
"prompt_examples": "..."
|
||
}
|
||
```
|
||
|
||
### POST /anima/generate
|
||
|
||
执行图片生成。支持 `repeat` 参数一次提交多个独立任务。
|
||
|
||
**请求体**：
|
||
|
||
```json
|
||
{
|
||
"aspect_ratio": "3:4",
|
||
"quality_meta_year_safe": "masterpiece, best quality, newest, year 2024, safe",
|
||
"count": "1girl",
|
||
"artist": "@fkey, @jima",
|
||
"tags": "upper body, smile, white dress",
|
||
"neg": "worst quality, low quality, blurry, bad hands, nsfw",
|
||
"repeat": 1
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"prompt_id": "uuid-xxx",
|
||
"positive": "masterpiece, best quality, ...",
|
||
"negative": "worst quality, ...",
|
||
"seed": 1234567890,
|
||
"width": 872,
|
||
"height": 1160,
|
||
"history_id": 12,
|
||
"images": [
|
||
{
|
||
"filename": "AnimaTool__00001_.png",
|
||
"subfolder": "",
|
||
"type": "output",
|
||
"view_url": "http://127.0.0.1:8188/view?filename=...",
|
||
"saved_path": "/path/to/outputs/AnimaTool__00001_.png",
|
||
"base64": "...",
|
||
"mime_type": "image/png",
|
||
"data_url": "data:image/png;base64,...",
|
||
"markdown": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> `repeat > 1` 时，响应为 `{"success": true, "results": [...]}`，每项结构同上。
|
||
|
||
### GET /anima/history
|
||
|
||
查看最近生成历史。
|
||
|
||
**参数**：`?limit=5`（默认 5，范围 1-50）
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"count": 2,
|
||
"records": [
|
||
{
|
||
"id": 12,
|
||
"timestamp": "2026-02-06T17:30:00",
|
||
"params": { "artist": "@fkey", "tags": "...", "..." : "..." },
|
||
"positive_text": "masterpiece, ...",
|
||
"seed": 1234567890,
|
||
"width": 872,
|
||
"height": 1160
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### POST /anima/reroll
|
||
|
||
基于历史记录重新生成。
|
||
|
||
**请求体**：
|
||
|
||
```json
|
||
{
|
||
"source": "last",
|
||
"overrides": {
|
||
"artist": "@ciloranko",
|
||
"repeat": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
> `source`：`"last"` 或历史 ID（如 `"12"`）。`overrides` 中的参数会覆盖原始记录。
|
||
> seed 不指定则自动随机。
|
||
|
||
**响应**：与 `/anima/generate` 一致。
|
||
|
||
---
|
||
|
||
## 独立 FastAPI Server
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
cd ComfyUI-AnimaTool
|
||
pip install fastapi uvicorn
|
||
python -m servers.http_server
|
||
```
|
||
|
||
默认运行在 `http://127.0.0.1:8000`。
|
||
|
||
### 路由
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/` | GET | 欢迎信息 |
|
||
| `/health` | GET | 健康检查 |
|
||
| `/schema` | GET | Tool Schema |
|
||
| `/knowledge` | GET | 专家知识 |
|
||
| `/generate` | POST | 执行生成（支持 repeat） |
|
||
| `/history` | GET | 查看生成历史 |
|
||
| `/reroll` | POST | 基于历史重新生成 |
|
||
| `/docs` | GET | Swagger UI |
|
||
|
||
### Swagger UI
|
||
|
||
访问 `http://127.0.0.1:8000/docs` 查看交互式 API 文档。
|
||
|
||
---
|
||
|
||
## CLI 工具
|
||
|
||
```bash
|
||
cd ComfyUI-AnimaTool
|
||
python -m servers.cli --help
|
||
```
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
python -m servers.cli \
|
||
--aspect-ratio "3:4" \
|
||
--quality "masterpiece, best quality, newest, year 2024, safe" \
|
||
--count "1girl" \
|
||
--artist "@fkey, @jima" \
|
||
--tags "upper body, smile, white dress" \
|
||
--neg "worst quality, low quality, blurry"
|
||
```
|