Moeblack-ComfyUI-AnimaTool/wiki/API-Reference.md

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

健康检查。

响应：

{
  "status": "ok",
  "comfyui_url": "http://127.0.0.1:8188",
  "tool_root": "/path/to/ComfyUI-AnimaTool"
}

GET /anima/schema

获取 Tool Schema（JSON Schema 格式）。

响应：

{
  "name": "generate_anima_image",
  "description": "...",
  "parameters": { ... }
}

GET /anima/knowledge

获取专家知识库。

响应：

{
  "anima_expert": "...",
  "artist_list": "...",
  "prompt_examples": "..."
}

POST /anima/generate

执行图片生成。支持 repeat 参数一次提交多个独立任务。

请求体：

{
  "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
}

响应：

{
  "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": "![AnimaTool__00001_.png](data:image/png;base64,...)"
    }
  ]
}

repeat > 1 时，响应为 {"success": true, "results": [...]}，每项结构同上。

GET /anima/history

查看最近生成历史。

参数：?limit=5（默认 5，范围 1-50）

响应：

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

基于历史记录重新生成。

请求体：

{
  "source": "last",
  "overrides": {
    "artist": "@ciloranko",
    "repeat": 3
  }
}

source："last" 或历史 ID（如 "12"）。overrides 中的参数会覆盖原始记录。 seed 不指定则自动随机。

响应：与 /anima/generate 一致。

---

独立 FastAPI Server

启动

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

cd ComfyUI-AnimaTool
python -m servers.cli --help

示例

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"