image_task 图生图改走 /images/edits:下载参考图后 multipart 上传

- 文生图仍走 /images/generations,图生图改走 /images/edits(原先错发到 generations 的 images 数组)
- X-Image-Task-Base-Url 统一剥离末尾 /images/generations 或 /images/edits,端点由模式决定
- 参考图先下载成字节再以 multipart 上传:60s 独立超时、20MB 流式上限、校验 image/*
- 同步 README / mcp README / package.json 说明
This commit is contained in:
2026-10-25 10:13:47 +08:00
parent bdc2de7128
commit d6b949969f
5 changed files with 205 additions and 50 deletions
+1 -1
View File
@@ -110,7 +110,7 @@ mcp_servers:
# url: "http://mcp_image_task:3000/mcp"
# headers:
# Authorization: Bearer <upstream-api-key>
# X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" # 任意 OpenAI 兼容的 /images/generations 上游
# X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" # 任意 OpenAI 兼容的 images 上游(生成 /images/generations、编辑 /images/edits)
# X-Image-Task-Model: "CogView-4"
# mode: skill
# - name: video_task
+4 -3
View File
@@ -5,7 +5,7 @@
| 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 |
|---|---|---|---|---|
| `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` |
| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(智谱原生或任意 OpenAI 兼容 `/images/generations`,单工具 op=create/get) | `3000` | `POST /mcp` |
| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` |
| `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` |
| `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` |
@@ -47,8 +47,9 @@ mcp_servers:
`image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取
(agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 用智谱 token;
`image_task` 走任意 OpenAI 兼容的 `/images/generations`,上游地址与模型分别由
`X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。所以这两个服务不用配任何密钥。
`image_task` 走任意 OpenAI 兼容的 images 上游:文生图 `/images/generations`、图生图 `/images/edits`,
上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。
所以这两个服务不用配任何密钥。
`asr` 同理:上游的 key / base_url / model 全部由调用方随请求 header 带入
(`Authorization` / `X-ASR-Base-Url` / `X-ASR-Model`,agent 侧配在 `config.yml` 的
+35 -13
View File
@@ -3,8 +3,8 @@
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成 / 编辑服务。
对外只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),异步任务契约与 `video_task` 一致。
上游必须是 OpenAI 兼容的 `/images/generations` 端点(智谱 `https://open.bigmodel.cn/api/paas/v4`
与各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization`
上游必须是 OpenAI 兼容的 images 端点:文生图走 `/images/generations`,图生图走 `/images/edits`
(智谱、各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization`
三个 header 都必填,服务不存密钥、也不预设厂商或默认模型。
- 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流)
@@ -75,8 +75,9 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r
`image` 是模式开关:
- 不传 → **文生图**;
- 传一个公网 URL → **图生图 / 编辑**。
- 不传 → **文生图**,请求 `POST <base>/images/generations`;
- 传一个公网 URL → **图生图 / 编辑**,服务先把这张图拉下来,再以 multipart 上传到
`POST <base>/images/edits`。
本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。
@@ -119,20 +120,36 @@ URL 由上游签名下发,**带有效期**(通常 24h),需要长期保
| Header | 必填 | 说明 |
|---|---|---|
| `Authorization` | ✅ | `Bearer <key>`,原样作为上游 Bearer token |
| `X-Image-Task-Base-Url` | ✅ | 上游 base URL(完整 `http(s)` 地址);已给到 `/images/generations` 就直接用,否则自动补上 |
| `X-Image-Task-Base-Url` | ✅ | 上游 base URL(完整 `http(s)` 地址,如 `https://<host>/v1`);若已给到 `/images/generations` 或 `/images/edits` 会自动剥回 base,再按模式拼端点 |
| `X-Image-Task-Model` | ✅ | 模型名原样透传 |
地址与模型只由 header 决定,AI 看不到也填不了;换模型 = 改 header 后重启 core。
### 图生图
传了 `image` 时,请求体带 `images: [url]`(数组形式)。是否支持由上游模型决定——不支持时
上游会回 4xx,`op=get` 里以 `task_status: FAIL` 呈现。
图生图**不能**走 `/images/generations`,必须走 `/images/edits`。服务会先把 `image` URL 下载成字节
(独立 60s 超时,单图上限 20MB,响应需是 `image/*`,如 png / jpeg / webp / gif / bmp),再以 multipart 上传:
```text
POST <base>/images/edits
Content-Type: multipart/form-data; boundary=...
model=<header 里的模型>
prompt=<prompt>
image=@<下载到的参考图> # 字段名 image,文件名按 MIME 补扩展名
n=1
response_format=url
```
选 multipart 而不是 JSON + base64 data URL:参考图已经在本地手里,直接当文件传可省掉 base64 的
1/3 体积膨胀,也避开网关对超大 JSON 体的限制。
### 请求体
固定 `{ model, prompt, n: 1, response_format: "url" }`,传图时追加 `images: [url]`。
`size` / `quality` 一律不传,交给上游默认值。
- 文生图:JSON `{ model, prompt, n: 1, response_format: "url" }` → `/images/generations`
- 图生图:multipart(字段见上)→ `/images/edits`
`size` / `quality` 一律不传,交给上游默认值。两种模式的成功响应都按 `data[0].url` 取图。
---
@@ -170,13 +187,15 @@ URL 由上游签名下发,**带有效期**(通常 24h),需要长期保
| 缺 `X-Image-Task-Base-Url` / 不是完整 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示填完整地址 |
| 缺 `X-Image-Task-Model` | `200`(MCP 工具返回) | `isError: true`,提示补 header |
| `image` 不是公网 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示只接受公网 URL,不接受文件上传 / base64 |
| 参考图下载失败 / 超时(>60s)/ 超过 20MB / 不是图片 | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,错误直述下载环节 |
| `op=create` 缺 prompt / `op=get` 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 |
| `op=get` 查不到任务 | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id |
| 上游 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,正文含上游状态码和 body |
| 上游只回 `b64_json` | `200`(MCP 工具返回) | `task_status: FAIL`,提示本服务只接受 URL |
| 网络失败 / 超时(>180s) | `200`(MCP 工具返回) | `task_status: FAIL`,不会出现永久 PROCESSING 的僵尸任务 |
> JSON 请求体上限保持 2MB:`image` 只接受 URL,不接收文件或 base64。
> JSON 请求体上限保持 2MB:工具参数里的 `image` 只接受 URL,不接收文件或 base64。
> 参考图由服务自己下载后以 multipart 转发给上游,不经过 MCP 请求体。
---
@@ -303,7 +322,8 @@ image_task/
- token / 上游地址 / 模型在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取
- **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用
- **模型 / 上游地址不入 schema**:只从 HTTP header 读取,AI 不可见
- **`image` 单一开关**:不传 = 文生图,传一个公网 URL = 图生图;`image` 是单个字符串,只接受公网 `http(s)` URL
- **`image` 单一开关**:不传 = 文生图(`/images/generations`),传一个公网 URL = 图生图
(下载后 multipart 上传 `/images/edits`);`image` 是单个字符串,只接受公网 `http(s)` URL
- **URL 提取**:只接受 `data[].url` 形式的 http(s) URL;上游若回 `b64_json` 则记 `FAIL` 并给出明确错误
---
@@ -320,10 +340,12 @@ A: 不需要重建 session,但 core 的 `mcp_servers[].headers` 是启动时
A: 当前上游契约只稳定支持单张;`image` 因此是单个 URL 字符串。
**Q: 图生图报错?**
A: 是否支持取决于上游模型;不支持时上游回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `images` 字段的模型即可。
A: 图生图走 `/images/edits` + multipart(字段名 `image`)。若上游模型不支持编辑、或网关不认这种入参,
上游会回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `/images/edits` 的模型即可。
**Q: 本地图片怎么传?**
A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。本服务不接受文件上传或 base64,上游服务器也无法访问你的本地路径。
A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。
本服务不接受文件上传或 base64(MCP 请求体不放图片字节),参考图由服务自己从这个 URL 拉取。
**Q: 上游是同步接口,为什么对外做成异步?**
A: 和 `video_task` 保持同一套任务型契约;同时避免一次生图把 core 的 `tools/call` 拖超时。
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "mcp_image_task",
"version": "1.0.0",
"description": "MCP server for image generation and editing via any OpenAI-compatible /images/generations endpoint (single tool image_task with op=create/get)",
"description": "MCP server for image generation and editing via any OpenAI-compatible images API (/images/generations and /images/edits), single tool image_task with op=create/get",
"type": "module",
"main": "src/mcp-server.js",
"scripts": {
+164 -32
View File
@@ -6,14 +6,19 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
// 上游必须是 OpenAI 兼容的 /images/generations 端点:Base-Url / 模型 / 凭据全部由调用方
// 随每个请求用 header 带入(X-Image-Task-Base-Url / X-Image-Task-Model / Authorization),
// 服务自己不存、也不预设任何厂商。
// 上游必须是 OpenAI 兼容的端点:文生图走 /images/generations,图生图走 /images/edits。
// Base-Url / 模型 / 凭据全部由调用方随每个请求用 header 带入(X-Image-Task-Base-Url /
// X-Image-Task-Model / Authorization),服务自己不存、也不预设任何厂商。
// 上游同步调用耗时上限(出图几十秒量级,留足余量)。
// 超时后任务记为 FAIL,避免上游挂而不回时永远卡在 PROCESSING。
const UPSTREAM_TIMEOUT_MS = 180_000;
// 图生图要先把参考图拉成字节再 multipart 上传:下载超时与体积都要单独兜底,
// 否则慢 CDN 会拖死任务、超大原图会顶满容器内存。
const IMAGE_DOWNLOAD_TIMEOUT_MS = 60_000;
const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
// ── 优雅退出 ──────────────────────────────────────────────────────────────
// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认
// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。
@@ -78,9 +83,10 @@ function pickModel(headers) {
return pickHeaderString(headers, "x-image-task-model");
}
// 解析 Base-Url:必须是完整 http(s) URL。已经给到 /images/generations 就直接用,
// 否则补在 base 后面。
function resolveEndpoint(rawBase) {
// 解析 Base-Url:必须是完整 http(s) URL。允许调用方直接填到 /images/generations 或
// /images/edits(老配置、照抄文档的写法),统一剥回 base,端点由 mode 决定——
// 否则图生图会被错发到 generations。
function resolveBaseUrl(rawBase) {
const base = String(rawBase || "").trim().replace(/\/+$/, "");
if (!base) {
throw new Error(
@@ -92,9 +98,12 @@ function resolveEndpoint(rawBase) {
`Invalid X-Image-Task-Base-Url "${base}": must be a full http(s) URL.`
);
}
return /\/images\/generations$/i.test(base)
? base
: base + "/images/generations";
return base.replace(/\/images\/(generations|edits)$/i, "");
}
// mode=edit 走 /images/edits(图生图),否则走 /images/generations(文生图)。
function resolveEndpoint(base, mode) {
return base + (mode === "edit" ? "/images/edits" : "/images/generations");
}
// 模型只由 header 决定,AI 看不到也填不了。不猜缺省值:猜错只会换来含义不明的 400。
@@ -114,29 +123,23 @@ function resolveTarget(headers) {
throw new Error('Missing Authorization: use "Authorization: Bearer <token>".');
}
return {
url: resolveEndpoint(pickBaseUrl(headers)),
base: resolveBaseUrl(pickBaseUrl(headers)),
token,
model: resolveModel(headers),
};
}
async function callImagesGenerations({ url, token, model, prompt, image }) {
// 统一按 OpenAI 兼容协议:单图 + response_format=url(b64_json 几十 MB,既塞不进
// 任务表也没法给模型看)。尺寸/质量一律不传,交给上游默认值。
// 传了 image 就是图生图;上游字段是数组,所以这里包一层。
const body = Object.assign(
{ model, prompt, n: 1, response_format: "url" },
image ? { images: [image] } : null
);
// 统一的上游 POST:超时、错误体解析都在这层,JSON 与 multipart 共用。
// contentType 为空表示交给 fetch 自己写(multipart 必须这样,boundary 由它生成)。
async function postUpstream({ url, token, body, contentType }) {
const headers = { Authorization: `Bearer ${token}` };
if (contentType) headers["Content-Type"] = contentType;
let resp;
try {
resp = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
headers,
body,
signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
});
} catch (e) {
@@ -165,6 +168,126 @@ async function callImagesGenerations({ url, token, model, prompt, image }) {
return data;
}
const MIME_TO_EXT = {
"image/png": "png",
"image/jpeg": "jpg",
"image/webp": "webp",
"image/gif": "gif",
"image/bmp": "bmp",
};
const EXT_TO_MIME = {
png: "image/png",
jpg: "image/jpeg",
jpeg: "image/jpeg",
webp: "image/webp",
gif: "image/gif",
bmp: "image/bmp",
};
function urlExtension(url) {
try {
const m = /\.([a-z0-9]+)$/i.exec(new URL(url).pathname);
return m ? m[1].toLowerCase() : "";
} catch {
return "";
}
}
// 判定参考图的 MIME:优先响应头,其次 URL 扩展名。响应头只要声明是 image/* 就放行
// (avif / tiff 这类冷门格式交给上游判断),避免本地图片被我们提前拒掉。
// 两者都不是图片就报错——典型情况是链接过期后拿到 HTML 错误页,继续上传只会换来
// 上游一句难懂的 400。
function pickImageMime(contentType, url) {
const ct = String(contentType || "").split(";")[0].trim().toLowerCase();
if (/^image\/[a-z0-9.+-]+$/.test(ct)) return ct;
const mime = EXT_TO_MIME[urlExtension(url)];
if (mime) return mime;
throw new Error(
`Reference image is not an image: content-type "${ct || "none"}" (${url}).`
);
}
// multipart 里的文件名按 MIME 补扩展名;冷门 image/* 就把子类型当年扩展名。
function extensionForMime(mime) {
return (
MIME_TO_EXT[mime] ||
mime.slice("image/".length).replace(/[^a-z0-9]/g, "") ||
"img"
);
}
// 图生图需要真实字节:先把 image URL 拉下来。带独立超时与体积上限,错误直述下载环节,
// 便于区分「参考图挂了」和「上游出图失败」。
async function downloadImage(url) {
let resp;
try {
resp = await fetch(url, {
signal: AbortSignal.timeout(IMAGE_DOWNLOAD_TIMEOUT_MS),
});
} catch (e) {
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
throw new Error(
`Failed to download reference image: timed out after ${IMAGE_DOWNLOAD_TIMEOUT_MS} ms (${url})`
);
}
throw new Error(`Failed to download reference image: ${e.message} (${url})`);
}
if (!resp.ok) {
throw new Error(
`Failed to download reference image: ${resp.status} ${resp.statusText} (${url})`
);
}
const declared = Number(resp.headers.get("content-length") || 0);
if (declared > MAX_IMAGE_BYTES) {
throw new Error(
`Reference image is too large: ${declared} bytes (limit ${MAX_IMAGE_BYTES}) (${url})`
);
}
// 不直接 arrayBuffer():没有 content-length 的响应会一路读进内存,
// 这里边读边计数,超限立刻中止(断掉上游连接)。
const chunks = [];
let total = 0;
for await (const chunk of resp.body) {
total += chunk.length;
if (total > MAX_IMAGE_BYTES) {
throw new Error(
`Reference image is too large: >${MAX_IMAGE_BYTES} bytes (limit ${MAX_IMAGE_BYTES}) (${url})`
);
}
chunks.push(chunk);
}
if (total === 0) {
throw new Error(`Reference image is empty (${url})`);
}
const buffer = Buffer.concat(chunks, total);
const mime = pickImageMime(resp.headers.get("content-type"), url);
return { buffer, mime, filename: `image.${extensionForMime(mime)}` };
}
// 文生图:JSON 体。response_format=url(b64_json 几十 MB,既塞不进任务表也没法给模型看)。
// 尺寸/质量一律不传,交给上游默认值。
async function callImagesGenerations({ url, token, model, prompt }) {
const body = JSON.stringify({ model, prompt, n: 1, response_format: "url" });
return postUpstream({ url, token, body, contentType: "application/json" });
}
// 图生图:上游只认 /images/edits,且实测只接受两种入参——
// 1) multipart/form-data,image 字段是文件(image=@a.jpg);
// 2) application/json,image 字段是 data:image/...;base64,... 的 data URL。
// 这里走 multipart:参考图已经在本地手里,直接当文件上传,省掉 base64 的 1/3 体积膨胀,
// 也避开网关对超大 JSON 体的限制。响应格式与 generations 一致(data[0].url)。
async function callImagesEdits({ url, token, model, prompt, image }) {
const ref = await downloadImage(image);
const form = new FormData();
form.append("model", model);
form.append("prompt", prompt);
form.append("image", new Blob([ref.buffer], { type: ref.mime }), ref.filename);
form.append("n", "1");
form.append("response_format", "url");
// 不传 Content-Type:fetch 会带上含 boundary 的 multipart/form-data
return postUpstream({ url, token, body: form });
}
// 只认 http(s) URL。b64_json 不再当 URL 存:它会把任务表撑爆,模型也读不了。
function extractUrls(data) {
if (!data) return [];
@@ -186,7 +309,7 @@ function hasInlineBase64(data) {
}
// ===== 自维护任务表(异步语义全靠这层模拟) =====
// 上游智谱 images 接口是同步阻塞的,但对外要和 video_task 一样提供
// 上游智谱/网关的 images 接口是同步阻塞的,但对外要和 video_task 一样提供
// create(立即返回 task_id)+ get(轮询结果)的异步契约:
// create 登记 PROCESSING 后把同步调用丢到后台跑,get 从表里读最新状态。
//
@@ -218,13 +341,21 @@ function pruneTasks() {
// 后台跑同步上游调用,结果回写任务表(fire-and-forget,不 await)
function runImageTask({ task, target, prompt, image }) {
callImagesGenerations({
url: target.url,
token: target.token,
model: target.model,
prompt,
image,
})
const upstream = image
? callImagesEdits({
url: resolveEndpoint(target.base, "edit"),
token: target.token,
model: target.model,
prompt,
image,
})
: callImagesGenerations({
url: resolveEndpoint(target.base, "generation"),
token: target.token,
model: target.model,
prompt,
});
upstream
.then((data) => {
task.finishedAt = Date.now();
const urls = extractUrls(data);
@@ -260,7 +391,8 @@ async function handleCreate({ args, headers }) {
};
}
// image 是文生图/图生图开关:不传 = 文生图;传一个公网 URL = 修图。
// image 是文生图/图生图开关:不传 = 文生图(/images/generations);传一个公网 URL = 修图
// (/images/edits,服务会先把这张图拉下来再以 multipart 上传)。
// 只接受公网 http(s) URL;本地文件请先由调用方用 mint_public_link 换成公网链接。
if (args.image !== undefined && typeof args.image !== "string") {
return {