# 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` 的实时返回，
上游上下线模型不会让文档失效。