105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# ai-image
|
||
|
||
绘图聚合服务。通过 REST API 或 MCP 调用任意已接入的生图上游。
|
||
|
||
## 服务地址
|
||
|
||
- Web 控制台 + REST：`http://127.0.0.1:8765/`
|
||
- MCP（streamable HTTP）：`http://127.0.0.1:8765/mcp`
|
||
- MCP（stdio 子进程）：`python main.py --stdio`
|
||
|
||
## 调用流程（必须按顺序）
|
||
|
||
1. `list_providers()` —— 列出可用供应商及其已启用模型数。
|
||
2. `discover_models(provider_id)` —— **必做**，拉取指定供应商的上游模型清单。
|
||
返回 `{provider_id, total, matched}`，`matched` 是模型 ID 转小写后包含 `image` 的集合。
|
||
3. `generate_image(...)` —— 出图，`model` 必须取自上一步的 `matched`。
|
||
|
||
> **`matched` 为空时**：上游没有 ID 含 `image` 的模型。必须**直接结束并回复「没找到有效的模型」**，
|
||
> 不得猜测模型名、不得调用出图接口。
|
||
|
||
## MCP 工具
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|---|---|---|
|
||
| `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` | — | 获取本文件最新内容 |
|
||
|
||
## 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` | 本文件内容 |
|
||
|
||
## 出图参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `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 | 画廊标识；建议显式传调用 Agent 的名称，例如 `codex`，决定落盘目录 |
|
||
|
||
## 落盘规则
|
||
|
||
图生图通过 REST/MCP 的 `images` 字段传入参考图。以下 REST 示例中的供应商和模型
|
||
须替换为发现接口返回且已启用的值；仅支持参考图的适配器（如 Agnes）可用：
|
||
|
||
```json
|
||
{
|
||
"provider_id": "<provider_id>",
|
||
"model": "<discovered_model_id>",
|
||
"prompt": "保留参考图的构图，调整为水彩风格",
|
||
"size": "1024x1024",
|
||
"n": 1,
|
||
"images": ["https://example.com/reference.png"],
|
||
"profile_name": "codex"
|
||
}
|
||
```
|
||
|
||
```
|
||
output/
|
||
└── <profile_name>/ ← 目录名 = 谁生成的图片
|
||
├── <model>-<id>.png
|
||
└── ...
|
||
```
|
||
|
||
- 网页端手动出图固定 `profile_name = user` → `output/user/`
|
||
- Agent 调用时建议显式将 `profile_name` 设为自己的名称（例如 `codex`），图片进入同名画廊。
|
||
- 服务端不会自动识别 Agent 身份；省略 `profile_name` 时 MCP 使用通用默认值 `agent`，它不代表具体 Agent 的名字。
|
||
- 目录不存在时后端自动创建
|
||
- 允许字符：字母、数字、下划线、短横线（1~64 位）
|
||
|
||
## 异常处理
|
||
|
||
- `matched` 为空 → 回复「没找到有效的模型」，停止流程。
|
||
- 上游返回 4xx/5xx → 出图工具返回 `{status: "failed", error: "..."}`，把错误原样告知用户，不要重试伪造结果。
|
||
- 供应商未配置密钥 → 先用 `list_providers` 确认该供应商存在，再提示用户在控制台「供应商」页填写。
|
||
|
||
## 模型清单
|
||
|
||
本文件**不包含任何固定模型名**。可用模型一律来自 `discover_models` 的实时返回，
|
||
上游上下线模型不会让文档失效。
|