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