feat: complete image console and add verified REST and MCP workflows

2026-11-04 00:41:54 +08:00
parent 3140cd51d2
commit bef8af53ed
48 changed files with 5167 additions and 1176 deletions
@@ -1,282 +1,103 @@
---
-name: ai-image
-description: Generate images via AI text-to-image API (GPT Image / Grok / Agnes Image 2.1 Flash). Use when the user asks to draw, paint, generate, or create an image from a text description, or to colorize / edit / remix existing images.
---
+# ai-image

-# AI 绘图工具
+绘图聚合服务。通过 REST API 或 MCP 调用任意已接入的生图上游。

-通过 FastAPI 文生图服务生成图片，供 Agent 通过 HTTP/cURL 直接调用，无需自己实现模型请求逻辑。
+## 服务地址

-服务端使用 OpenAI Python SDK 请求 GPT Image / Grok Image 上游接口，生成的图片保存在服务端 `output/<profile_name>/` 目录，并通过 HTTP 返回访问地址。
+- Web 控制台 + REST：`http://127.0.0.1:8765/`
+- MCP（streamable HTTP）：`http://127.0.0.1:8765/mcp`
+- MCP（stdio 子进程）：`python main.py --stdio`

-## 可用脚本
+## 调用流程（必须按顺序）

-| 能力 | 服务端文件 | HTTP 端点 | 模型 |
-|------|------------|------------|------|
-| GPT / Grok 绘图 | `main.py` | `POST /images/generations` | `gpt-image-2-1K` / `gpt-image-2-2K` / `gpt-image-2-4K` / `grok-imagine-image-lite` |
-| Agnes 绘图（文生图 / 图生图 / 多图合成） | `main.py` | `POST /agnes/images/generations` | `agnes-image-2.1-flash` |
-| Agnes 上传版（图生图 / 多图合成，multipart） | `main.py` | `POST /agnes/images/generations/upload` | `agnes-image-2.1-flash` |
-| 健康检查 | `main.py` | `GET /health` | — |
-| 图片访问 | `main.py` | `GET /output/{profile_name}/{filename}` | — |
+1. `list_providers()` —— 列出可用供应商及其已启用模型数。
+2. `discover_models(provider_id)` —— **必做**，拉取指定供应商的上游模型清单。
+   返回 `{provider_id, total, matched}`，`matched` 是模型 ID 转小写后包含 `image` 的集合。
+3. `generate_image(...)` —— 出图，`model` 必须取自上一步的 `matched`。

-## GPT 模型说明
+> **`matched` 为空时**：上游没有 ID 含 `image` 的模型。必须**直接结束并回复「没找到有效的模型」**，
+> 不得猜测模型名、不得调用出图接口。

-| 模型 | 输出尺寸 | 备注 |
-|------|----------|------|
-| `gpt-image-2-1K` | 不固定 | 线路不稳定，可能 503，多试几次(隔十秒) |
-| `gpt-image-2-2K` | 不固定 | 线路不稳定，可能 503，多试几次(隔十秒) |
-| `gpt-image-2-4K` | 不固定 | 线路不稳定，可能 503，多试几次(隔十秒) |
+## MCP 工具

-```text
-注意, gpt-image-2 画图效果好, 但是有个能出现线路拥堵情况,如果报错,请重试
-可以尝试 gpt-image-2-1K, gpt-image-2-2K, gpt-image-2-4K, 三个模型都尝试一下
-可以生成 1:1, 4:3, 16:9 的图片
-```
+| 工具 | 参数 | 说明 |
+|---|---|---|
+| `list_providers` | — | 第 1 步，列出可用供应商 |
+| `discover_models` | `provider_id` | 第 2 步（必做），返回 `{provider_id, total, matched}` |
+| `generate_image` | `provider`, `model`, `prompt`, `size`, `ratio`, `n`, `images`, `profile_name` | 第 3 步，出图 |
+| `list_generations` | `limit` | 查询最近生成记录 |
+| `get_skill_doc` | — | 获取本文件最新内容 |

-> Grok 模型的 size 参数不可靠，API 返回尺寸不受控。
+## REST 端点

-## 使用方式
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/health` | 健康检查 |
+| GET | `/api/providers` | 供应商列表（密钥掩码） |
+| POST | `/api/providers` | 新增 / 更新供应商 |
+| DELETE | `/api/providers/{id}` | 删除供应商及其模型 |
+| POST | `/api/providers/discover` | 手填 Base URL + Key 临时拉模型 |
+| POST | `/api/providers/{id}/discover` | 按已保存供应商拉模型（写库） |
+| POST | `/api/providers/{id}/models` | 保存勾选的模型 |
+| GET | `/api/models` | 模型列表（可 `?provider_id=`） |
+| PATCH | `/api/models/{id}` | 启用 / 停用单个模型 |
+| POST | `/api/models/bulk` | 批量启用 / 停用 |
+| POST | `/api/generate` | 出图 |
+| GET | `/api/generations` | 生成记录 |
+| GET | `/api/galleries` | 画廊列表 |
+| GET | `/api/galleries/{profile}` | 画廊内图片 |
+| DELETE | `/api/galleries/{profile}/{filename}` | 删除图片 |
+| GET | `/api/skills` | 本文件内容 |

-默认服务地址为 `http://localhost:8765`。
+## 出图参数

-健康检查：
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `provider` / `provider_id` | str | 供应商 ID，来自 `list_providers` |
+| `model` | str | 模型 ID，来自 `discover_models` 的 `matched` |
+| `prompt` | str | 提示词 |
+| `size` | str | 统一 `WxH` 像素，如 `1024x1024`；也支持 `1K`/`2K`/`3K`/`4K` 档位 |
+| `ratio` | str | 仅 Agnes 支持，如 `16:9`；省略时从 `size` 推导 |
+| `n` | int | 生成数量（1~4） |
+| `images` | list[str] | 图生图参考图（URL 或 Data URI），仅部分供应商支持 |
+| `profile_name` | str | 调用方标识，决定落盘目录 |

-```bash
-curl http://localhost:8765/health
-```
+## 落盘规则

-使用 Grok 绘图：
-
-```bash
-curl -X POST http://localhost:8765/images/generations \
-  -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "a cute cat",
-    "provider": "grok",
-    "size": "1024x1024",
-    "n": 1,
-    "profile_name": "profile_name"
-  }'
-```
-
-使用 GPT 绘图：
-
-```bash
-curl -X POST http://localhost:8765/images/generations \
-  -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "a cute cat",
-    "provider": "gpt",
-    "model": "gpt-image-2-1K",
-    "size": "1536x1024",
-    "n": 1,
-    "profile_name": "profile_name"
-  }'
-```
-
-生成结果中的 `url` 为图片访问地址，例如 `http://localhost:8765/output/{profile_name}/{filename}`。
-
-## Agnes Image 2.1 Flash
-
-升级版图像生成模型，针对高信息密度图像和复杂构图做了优化。同时支持**文生图、图生图、多图合成**。
-
-### 调用示例
-
-文生图（2K, 16:9）：
-
-```bash
-curl -X POST http://localhost:8765/agnes/images/generations \
-  -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "a luminous floating city above a misty canyon at sunrise, cinematic realism",
-    "size": "2K",
-    "ratio": "16:9",
-    "profile_name": "profile_name"
-  }'
-```
-
-图生图（传入参考图 URL 或 Data URI Base64）：
-
-```bash
-curl -X POST http://localhost:8765/agnes/images/generations \
-  -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "turn the scene into a rainy cyberpunk night while preserving the original composition",
-    "size": "1K",
-    "ratio": "16:9",
-    "images": ["https://example.com/input.png"],
-    "profile_name": "profile_name"
-  }'
-```
-
-多图合成（`images` 传多张）：
-
-```bash
-curl -X POST http://localhost:8765/agnes/images/generations \
-  -H "Content-Type: application/json" \
-  -d '{
-    "prompt": "combine the two characters into an intense fantasy battle scene, dynamic lighting",
-    "size": "1K",
-    "ratio": "16:9",
-    "images": [
-      "https://example.com/character-1.png",
-      "https://example.com/character-2.png"
-    ],
-    "profile_name": "profile_name"
-  }'
-```
-
-响应示例：
+图生图通过 REST/MCP 的 `images` 字段传入参考图。以下 REST 示例中的供应商和模型
+须替换为发现接口返回且已启用的值；仅支持参考图的适配器（如 Agnes）可用：

 ```json
 {
-  "model": "agnes-image-2.1-flash",
-  "size": "2624x1472",
-  "ratio": "16:9",
-  "images": [
-    {"filename": "agnes-image-2.1-flash-xxxx.png", "url": "/output/profile_name/agnes-image-2.1-flash-xxxx.png", "bytes": 1234567}
-  ]
+  "provider_id": "<provider_id>",
+  "model": "<discovered_model_id>",
+  "prompt": "保留参考图的构图，调整为水彩风格",
+  "size": "1024x1024",
+  "n": 1,
+  "images": ["https://example.com/reference.png"],
+  "profile_name": "agent"
 }
 ```

-返回的 `size` 是根据 `size` 档位 + `ratio` 解析出的实际像素尺寸，便于拼接访问地址。
-
-### 上传版（multipart/form-data）
-
-如果不想手动 base64，可以用 `POST /agnes/images/generations/upload`，直接传本地图片文件：
-
-单张图：
-
-```bash
-curl -X POST http://localhost:8765/agnes/images/generations/upload \
-  -F "prompt=color this line art with watercolor style, soft palette, preserve composition" \
-  -F "profile_name=tester" \
-  -F "size=1K" \
-  -F "ratio=16:9" \
-  -F "images=@/path/to/your-image.png"
+```
+output/
+└── <profile_name>/        ← 目录名 = 谁生成的图片
+    ├── <model>-<id>.png
+    └── ...
 ```

-多张图（多图合成，`images` 字段可以传多次）：
+- 网页端手动出图固定 `profile_name = user` → `output/user/`
+- Agent 调用时由调用方指定 `profile_name`，默认 `agent`
+- 目录不存在时后端自动创建
+- 允许字符：字母、数字、下划线、短横线（1~64 位）

-```bash
-curl -X POST http://localhost:8765/agnes/images/generations/upload \
-  -F "prompt=combine the two characters into an intense fantasy battle scene" \
-  -F "profile_name=tester" \
-  -F "size=1K" \
-  -F "ratio=16:9" \
-  -F "images=@/path/to/character-1.png" \
-  -F "images=@/path/to/character-2.png"
-```
+## 异常处理

-Form 字段：
+- `matched` 为空 → 回复「没找到有效的模型」，停止流程。
+- 上游返回 4xx/5xx → 出图工具返回 `{status: "failed", error: "..."}`，把错误原样告知用户，不要重试伪造结果。
+- 供应商未配置密钥 → 先用 `list_providers` 确认该供应商存在，再提示用户在控制台「供应商」页填写。

- `prompt`：必填，文本提示词
- `profile_name`：必填，调用方 agent 的标识
- `size`：可选，默认 `1K`
- `ratio`：可选，宽高比；支持 `1:1` / `3:4` / `4:3` / `16:9` / `9:16` / `2:3` / `3:2` / `21:9`；默认 `1:1`
- `images`：必填，至少上传 1 张，支持 PNG / JPEG / WebP；多张传多个 `images` 字段即可
+## 模型清单

-响应格式与 JSON 版完全一致。
-
-### 请求参数
-
-请求体为 JSON，发送到 `POST /agnes/images/generations`：
-
- `profile_name`：**必填**，调用方 agent 的标识，图片会保存到 `output/<profile_name>/`
- `prompt`：必填，文本提示词
- `size`：可选，尺寸档位 `1K` / `2K` / `3K` / `4K`，或精确尺寸如 `1024x1024`；默认 `1K`
- `ratio`：可选，宽高比，与 `size` 档位配合使用；支持 `1:1` / `3:4` / `4:3` / `16:9` / `9:16` / `2:3` / `3:2` / `21:9`；默认 `1:1`
- `images`：可选，图生图或多图合成的输入图像 URL 或 Data URI Base64 列表
-
-### 输出尺寸参考
-
-| Ratio  | 1K          | 2K          | 3K          | 4K          |
-|--------|-------------|-------------|-------------|-------------|
-| `1:1`  | `1024x1024` | `2048x2048` | `3072x3072` | `4096x4096` |
-| `3:4`  | `864x1152`  | `1728x2304` | `2592x3456` | `3456x4608` |
-| `4:3`  | `1152x864`  | `2304x1728` | `3456x2592` | `4608x3456` |
-| `16:9` | `1312x736`  | `2624x1472` | `3936x2208` | `5248x2944` |
-| `9:16` | `736x1312`  | `1472x2624` | `2208x3936` | `2944x5248` |
-| `2:3`  | `832x1248`  | `1664x2496` | `2496x3744` | `3328x4992` |
-| `3:2`  | `1248x832`  | `2496x1664` | `3744x2496` | `4992x3328` |
-| `21:9` | `1568x672`  | `3136x1344` | `4704x2016` | `6272x2688` |
-
-### 使用注意
-
- 需要服务端配置 `AGNES_API_KEY`（默认走 `https://apihub.agnes-ai.com/v1`，可用 `AGNES_API_BASE_URL` 覆盖）
- 单次上游请求超时为 360 秒，建议客户端超时 ≥ 60s
- 上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
- 图生图 / 多图合成的参考图必须是可公开访问的 HTTPS URL，否则请用 Data URI Base64
- 当前定价：免费（`$0 / 张`）
-
-## 调用建议
-
- **优先用 Grok**：稳定出图，适合日常使用
- **追求画质用 GPT 1K**：请求中设置 `"provider": "gpt"`
- **GPT 2K/4K 线路可能不稳定**：不推荐作为默认模型
- **Prompt 用英文**：效果通常比中文好
- 使用 Docker Compose 时，项目的 `output/` 会映射到容器的 `/app/output`
-
-## 请求参数
-
-请求体为 JSON，发送到 `POST /images/generations`：
-
- `profile_name`：**必填**，调用方 agent 的标识（建议用 agent 名称），不填会报 422 错误；图片会保存到 `output/<profile_name>/` 目录
- `prompt`：必填，图片提示词
- `provider`：可选，`grok` 或 `gpt`，默认 `grok`
- `model`：可选，覆盖 provider 的默认模型
- `size`：可选，默认 `1024x1024`
- `n`：可选，生成数量，范围 `1 ~ 10`，默认 `1`
-
-## 输出规范
-
- 图片保存在服务端 `output/<profile_name>/` 目录，按调用方 agent 区分
- 响应返回 `filename`、`url` 和文件大小 `bytes`
- 图片通过 `GET /output/{profile_name}/{filename}` 访问
- 服务启动后，响应中的相对路径 `url` 需要拼接服务地址，例如 `http://localhost:8765/output/{profile_name}/{filename}`
-
-## Prompt 技巧
-
-### 基本结构
-
-一个高质量的 prompt 建议包含：**主体 + 动作/状态 + 环境 + 光线 + 风格 + 情绪 + 画质后缀**。描述越具体，出图越符合预期。
-
-```text
-[主体] [动作/状态]，[环境/场景]，[光线]，[风格]，[情绪]，[画质后缀]
-```
-
-### 示例对比
-
-| 模糊（效果差） | 具体（效果好） |
-|---|---|
-| `a cat` | `a fluffy orange tabby cat sleeping on a windowsill, warm afternoon sunlight, cozy living room, photorealistic, peaceful mood, cinematic lighting, highly detailed` |
-| `a car` | `a red sports car driving on a mountain road at sunset, golden hour light, dramatic clouds, cinematic wide shot, sense of speed, 4K, highly detailed` |
-| `a girl` | `a young girl with braided hair reading a book under a cherry blossom tree, soft morning light, anime style, nostalgic mood, detailed illustration` |
-
-### 常用要素清单
-
- **光线**：golden hour、soft morning light、neon lights、candlelight、cinematic lighting、studio lighting
- **风格**：photorealistic、anime style、watercolor、oil painting、3D render、pixel art、cyberpunk、minimalist
- **情绪**：peaceful、mysterious、energetic、nostalgic、romantic、dark
- **画质后缀**：highly detailed、8K、sharp focus、award winning photography
-
-### 尺寸参数
-
-`size` 是请求体里的 JSON 字段，不是命令行参数：
-
- 正方形：`"size": "1024x1024"`
- 横版：`"size": "1536x1024"`（仅 GPT 1K 稳定支持）
- Grok 模型的 `size` 不可靠，输出尺寸不受控，建议固定用 `1024x1024`
-
-### 其他建议
-
- 使用英文 prompt 效果通常比中文好
- 需要保持系列风格一致时，把风格描述固定写在 prompt 末尾
- 想要照片质感：加 `photorealistic, cinematic lighting, highly detailed`
- 想要插画/二次元风：指明 `anime style, detailed illustration` 或 `watercolor` 等风格词
-
-## 配置与注意事项
-
- 单次上游请求超时为 120 秒
- 上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
- FastAPI 自动文档地址：`http://localhost:8765/docs`
+本文件**不包含任何固定模型名**。可用模型一律来自 `discover_models` 的实时返回，
+上游上下线模型不会让文档失效。