refactor(video_task): 改成通用 OpenAI 兼容形态,不绑定任何厂商

照 image_task 的口径:Base-Url / 模型 / 凭据全部由调用方每个请求用 header 带入
(X-Video-Task-Base-Url / X-Video-Task-Model / Authorization),服务端不存密钥、
不预设默认模型、不认任何厂商专有字段。

- 提交 POST {base}/videos/generations(wait=false,立刻回 task_id)
- 查询 GET  {base}/videos/{task_id}
- 缺 header 同步报错,不打上游
- 上游只需回 task_id/id 与 status(completed 时带 videos[].url)
- presets.json 与 README 同步改成通用描述
This commit is contained in:
2026-11-17 16:28:44 +08:00
parent c750393c81
commit 3139108838
4 changed files with 303 additions and 293 deletions
+177 -208
View File
@@ -1,8 +1,4 @@
#!/usr/bin/env node
// MCP 视频任务服务:对接 WorkBuddy 网关(wb.ai)的 OpenAI 兼容视频接口
// 提交 POST /v1/videos/generations(wait=false,立刻回 task_id)
// 查询 GET /v1/videos/{task_id}
// 只有一条工具 video_task,用 op 区分 create / get;服务端不轮询,AI 自己查。
import express from "express";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -10,22 +6,13 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
// 上游网关地址:容器内可用 WB_BASE_URL 覆盖
const WB_BASE = (process.env.WB_BASE_URL || "https://wb.ai.foresh.com").replace(/\/+$/, "");
const SUBMIT_URL = `${WB_BASE}/v1/videos/generations`;
const queryUrl = (id) => `${WB_BASE}/v1/videos/${encodeURIComponent(id)}`;
// 上游必须是 OpenAI 兼容的视频端点:提交 POST /videos/generations,查询 GET /videos/{task_id}。
// Base-Url / 模型 / 凭据全部由调用方随每个请求用 header 带入(X-Video-Task-Base-Url /
// X-Video-Task-Model / Authorization),服务自己不存、也不预设任何厂商。
// 默认模型:minimax 出片约 2 分钟、扣 57 积分;kling 约 8 分钟、扣 103 积分
const DEFAULT_MODEL = "cn:minimax-video-h3";
const DEFAULT_SECONDS = 4;
// 提交/查询都是快接口(wait=false 立刻返回),卡住基本等于上游挂了
// 提交与查询都是快接口(wait=false 立刻回 task_id),卡住基本等于上游挂了。
const UPSTREAM_TIMEOUT_MS = 60_000;
// 上游状态归一:命中终态才停轮询
const DONE = new Set(["completed", "succeeded", "success"]);
const FAILED = new Set(["failed", "error", "cancelled", "canceled"]);
// ── 优雅退出 ──────────────────────────────────────────────────────────────
// 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认
// 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。
@@ -38,7 +25,7 @@ function shutdown(sig) {
shuttingDown = true;
console.log(`[video] received ${sig}, shutting down`);
closeAllSessions();
if (!httpServer) process.exit(0);
if (!httpServer) process.exit(0); // stdio 模式无监听,直接退
httpServer.close(() => process.exit(0));
setTimeout(() => process.exit(0), 3000).unref();
}
@@ -56,65 +43,94 @@ function parseArgs(argv) {
return args;
}
// 鉴权:每个请求从 header 取 wb.ai 的 API Key,服务端不落盘
function pickToken(headers) {
// 对外只有三个 header:Authorization / X-Video-Task-Base-Url / X-Video-Task-Model。
function pickAuthToken(headers) {
if (!headers) return null;
const candidates = [
headers["x-video-task-token"],
headers["x-mcp-token"],
headers["authorization"],
];
for (const v of candidates) {
if (!v) continue;
const s = String(v).trim();
if (!s) continue;
if (/^Bearer\s+/i.test(s)) {
const t = s.replace(/^Bearer\s+/i, "").trim();
if (t) return t;
} else {
return s;
}
const s = String(headers["authorization"] || "").trim();
if (!s) return null;
if (/^Bearer\s+/i.test(s)) {
const t = s.replace(/^Bearer\s+/i, "").trim();
return t || null;
}
return null;
return s;
}
function pickModel(headers) {
function pickHeaderString(headers, name) {
if (!headers) return null;
const v = headers["x-video-task-model"] || headers["x-mcp-model"] || headers["x-model"];
if (!v) return null;
const v = headers[name];
if (v === undefined || v === null) return null;
const s = String(v).trim();
return s || null;
}
// 网关的模型名一定带域前缀(cn: / global:)。旧配置里遗留的智谱模型名
// (cogvideox-flash 之类)没有冒号,发上去会 400「route config not found」,
// 统一回落到默认模型,老配置不用改也能用。
function normalizeModel(m) {
if (!m) return DEFAULT_MODEL;
return m.includes(":") ? m : DEFAULT_MODEL;
function pickBaseUrl(headers) {
return pickHeaderString(headers, "x-video-task-base-url");
}
async function callWb({ url, token, method = "POST", body }) {
function pickModel(headers) {
return pickHeaderString(headers, "x-video-task-model");
}
// 解析 Base-Url:必须是完整 http(s) URL。允许调用方直接填到 /videos/generations
// 或 /videos(照抄文档的写法),统一剥回 base——否则查询会被拼成两条路径。
function resolveBaseUrl(rawBase) {
const base = String(rawBase || "").trim().replace(/\/+$/, "");
if (!base) {
throw new Error(
"Missing X-Video-Task-Base-Url: pass the upstream base URL (e.g. https://<host>/v1)."
);
}
if (!/^https?:\/\//i.test(base)) {
throw new Error(
`Invalid X-Video-Task-Base-Url "${base}": must be a full http(s) URL.`
);
}
return base.replace(/\/videos(\/generations)?$/i, "");
}
// 模型只由 header 决定,AI 看不到也填不了。不猜缺省值:猜错只会换来含义不明的 400。
function resolveModel(headers) {
const model = pickModel(headers);
if (!model) {
throw new Error("Missing X-Video-Task-Model: pass the upstream model name.");
}
return model;
}
// 一次解析出本次请求的上游、凭据、模型。配置问题同步抛错,直接回给调用方。
function resolveTarget(headers) {
const token = pickAuthToken(headers);
if (!token) {
throw new Error('Missing Authorization: use "Authorization: Bearer <token>".');
}
return {
base: resolveBaseUrl(pickBaseUrl(headers)),
token,
model: resolveModel(headers),
};
}
// 统一的上游请求:超时、错误体解析都在这层,提交与查询共用。
async function callUpstream({ url, token, method = "POST", body }) {
const init = {
method,
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
headers: { Authorization: `Bearer ${token}` },
signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
};
if (body !== undefined) init.body = JSON.stringify(body);
if (body !== undefined) {
init.headers["Content-Type"] = "application/json";
init.body = JSON.stringify(body);
}
let resp;
try {
resp = await fetch(url, init);
} catch (e) {
// AbortSignal.timeout 中止时抛 TimeoutError/AbortError,转成明确的超时错误
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
throw new Error(`上游 ${UPSTREAM_TIMEOUT_MS} ms 内没有响应`);
throw new Error(`Upstream request timed out after ${UPSTREAM_TIMEOUT_MS} ms`);
}
throw e;
}
const text = await resp.text();
let data;
try {
@@ -123,9 +139,7 @@ async function callWb({ url, token, method = "POST", body }) {
data = { raw: text };
}
if (!resp.ok) {
// 网关的错误体是 {error:{message}},取原话给模型看,便于自行纠错
const msg = data?.error?.message || data?.error?.code || text.slice(0, 300);
const err = new Error(`网关返回 ${resp.status}: ${msg}`);
const err = new Error(`Upstream error: ${resp.status} ${resp.statusText} - ${text}`);
err.status = resp.status;
err.detail = data;
throw err;
@@ -133,62 +147,74 @@ async function callWb({ url, token, method = "POST", body }) {
return data;
}
// ===== op=create:提交任务,wait=false 立刻返回 task_id =====
async function submitVideo({ token, model, prompt, imageUrl, seconds, aspectRatio, resolution, negativePrompt, enableAudio }) {
const body = { model, prompt, wait: false };
if (imageUrl) body.image = imageUrl;
if (seconds) body.seconds = seconds;
if (aspectRatio) body.aspect_ratio = aspectRatio;
// ===== op=create:提交视频生成(wait=false,立刻返回 task_id)=====
async function submitVideo({ base, token, model, prompt, image_url, seconds, aspect_ratio, resolution, negative_prompt, enable_audio }) {
const body = { model, wait: false };
if (prompt) body.prompt = prompt;
if (image_url) body.image = image_url; // OpenAI Videos 口径的参考图字段
if (seconds !== undefined) body.seconds = seconds;
if (aspect_ratio) body.aspect_ratio = aspect_ratio;
if (resolution) body.resolution = resolution;
if (negativePrompt) body.negative_prompt = negativePrompt;
if (enableAudio !== undefined && enableAudio !== null) body.enable_audio = Boolean(enableAudio);
return await callWb({ url: SUBMIT_URL, token, body });
if (negative_prompt) body.negative_prompt = negative_prompt;
if (enable_audio !== undefined) body.enable_audio = Boolean(enable_audio);
return await callUpstream({ url: base + "/videos/generations", token, body });
}
// ===== op=get:查任务(单次拉取) =====
async function queryVideo({ token, taskId }) {
return await callWb({ url: queryUrl(taskId), token, method: "GET" });
// ===== op=get:查询任务(单次拉取,不内部轮询)=====
async function queryVideo({ base, token, taskId }) {
return await callUpstream({
url: base + "/videos/" + encodeURIComponent(taskId),
token,
method: "GET",
});
}
function normStatus(s) {
return String(s || "").trim().toLowerCase();
const DONE = new Set(["completed", "succeeded", "success"]);
const FAILED = new Set(["failed", "error", "cancelled", "canceled"]);
function normalizeStatus(s) {
return String(s || "").toLowerCase();
}
async function handleCreate({ args, headers, token }) {
// ---------- op=create 的业务处理 ----------
async function handleCreate({ args, headers }) {
// 纯空白 prompt 等同没给:schema 只校验类型/长度,不校验内容。
const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
if (!prompt) {
if (!prompt && !args.image_url) {
return {
isError: true,
content: [{ type: "text", text: 'op=create 需要 "prompt"(视频描述,必填)。' }],
content: [{ type: "text", text: 'op=create requires at least one of "prompt" or "image_url".' }],
};
}
const model = normalizeModel(pickModel(headers));
const seconds = Number.isFinite(args.seconds) ? args.seconds : DEFAULT_SECONDS;
let target;
try {
target = resolveTarget(headers);
} catch (e) {
return { isError: true, content: [{ type: "text", text: e.message }] };
}
try {
const data = await submitVideo({
token,
model,
...target,
prompt,
imageUrl: args.image_url,
seconds,
aspectRatio: args.aspect_ratio,
image_url: args.image_url,
seconds: args.seconds,
aspect_ratio: args.aspect_ratio,
resolution: args.resolution,
negativePrompt: args.negative_prompt,
// 兼容旧字段名
enableAudio: args.enable_audio ?? args.with_audio,
negative_prompt: args.negative_prompt,
enable_audio: args.enable_audio ?? args.with_audio,
});
const taskId = data.task_id || data.id;
const summary =
`model: ${data.model || model}\n` +
`task_id: ${taskId}\n` +
`status: ${normStatus(data.status) || "queued"}\n` +
`model: ${target.model}\n` +
`status: ${data.status || "queued"}\n` +
`\n` +
`视频是异步生成(minimax 约 2 分钟,kling 约 8 分钟)。` +
`之后用 op="get" 加 task_id="${taskId}" 查询,直到 status 变成 completed 或 failed。` +
`不要重复提交同一个任务。`;
`Video generation is asynchronous. ` +
`Call this tool again with op="get" and task_id="${taskId}" to fetch the result.`;
return { content: [{ type: "text", text: summary }] };
} catch (e) {
@@ -197,177 +223,131 @@ async function handleCreate({ args, headers, token }) {
content: [
{
type: "text",
text: `提交视频任务失败:${e.message}`,
text: `提交视频任务失败:${e.message}${e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : ""}`,
},
],
};
}
}
async function handleGet({ args, token }) {
// ---------- op=get 的业务处理 ----------
async function handleGet({ args, headers }) {
// 纯空白 task_id 不能直接拼进上游路径,否则得到一条含编码后空白的报错。
const taskId = typeof args.task_id === "string" ? args.task_id.trim() : "";
if (!taskId) {
return {
isError: true,
content: [{ type: "text", text: 'op=get 需要 "task_id"。' }],
};
return { isError: true, content: [{ type: "text", text: 'op=get requires "task_id".' }] };
}
let target;
try {
target = resolveTarget(headers);
} catch (e) {
return { isError: true, content: [{ type: "text", text: e.message }] };
}
try {
const data = await queryVideo({ token, taskId });
const status = normStatus(data.status) || "unknown";
const data = await queryVideo({ ...target, taskId });
const status = normalizeStatus(data.status);
if (DONE.has(status)) {
const url = (data.videos || [])[0]?.url;
const url = (data.videos || [])[0]?.url || (data.data || [])[0]?.url;
if (!url) {
return {
isError: true,
content: [
{
type: "text",
text: `任务已完成但没有返回视频地址。原始响应:${JSON.stringify(data).slice(0, 500)}`,
},
],
content: [{ type: "text", text: `任务已完成但没有视频地址。Raw: ${JSON.stringify(data).slice(0, 500)}` }],
};
}
const credit = data.usage?.credit;
const summary =
const text =
`task_id: ${taskId}\n` +
`model: ${data.model || "-"}\n` +
`model: ${data.model || target.model}\n` +
`status: completed\n` +
`Video URL: ${url}\n` +
(credit !== undefined ? `credit: ${credit}\n` : "") +
`\n注意:视频是签名直链,约 12 小时失效;要长期保存请立刻下载到本地。`;
return { content: [{ type: "text", text: summary }] };
(data.hint ? `note: ${data.hint}\n` : "");
return { content: [{ type: "text", text }] };
}
if (FAILED.has(status)) {
return {
isError: true,
content: [
{
type: "text",
text:
`task_id: ${taskId}\n` +
`status: ${status}\n` +
(data.error ? `error: ${JSON.stringify(data.error)}\n` : "") +
`任务已失败,需要换提示词或模型重新提交。`,
},
],
};
}
// queued / in_progress:告诉模型继续等,别重复提交
const progress = data.progress;
const errBlock = data.error ? `\nerror: ${JSON.stringify(data.error)}` : "";
const progress = data.progress !== undefined ? `\nprogress: ${data.progress}` : "";
return {
isError: FAILED.has(status),
content: [
{
type: "text",
text:
`task_id: ${taskId}\n` +
`model: ${data.model || "-"}\n` +
`status: ${status}` +
(progress !== undefined && progress !== null ? `(进度 ${progress}%)` : "") +
`\n还没出片,稍后再用 op="get" 查一次。`,
text: `task_id: ${taskId}\nmodel: ${data.model || target.model}\nstatus: ${data.status || "unknown"}${progress}${errBlock}`,
},
],
};
} catch (e) {
return {
isError: true,
content: [{ type: "text", text: `查询视频任务失败:${e.message}` }],
content: [
{
type: "text",
text: `查询视频任务失败:${e.message}${e.detail ? `\nDetails: ${JSON.stringify(e.detail)}` : ""}`,
},
],
};
}
}
function buildServer() {
const server = new McpServer(
{ name: "video_task", version: "2.0.0" },
{ capabilities: { tools: {} } }
);
const server = new McpServer({ name: "video_task", version: "2.0.0" }, { capabilities: { tools: {} } });
server.tool(
"video_task",
`AI 视频生成任务(异步)。
`AI video generation task (async).
操作:
- \`create\`:提交视频生成,必须给 \`prompt\`。立刻返回 \`task_id\`,生成在后台跑。
- \`get\`:用 \`task_id\` 查进度,出片后返回视频直链。
Operations:
- \`create\`: Start a new task. Requires at least one of \`prompt\` or \`image_url\`. Returns \`task_id\` immediately.
- \`get\`: Check a task by \`task_id\`. Returns status and, when completed, the video URL.
示例:
- 文生视频 → \`{"op":"create","prompt":"一只橘猫在阳光下的草地上奔跑,电影感"}\`
- 图生视频 → \`{"op":"create","prompt":"画面里的人缓缓转身","image_url":"https://..."}\`
- 查任务 → \`{"op":"get","task_id":"<create 返回的 task_id>"}\`
Examples:
- Text-to-video → \`{"op":"create","prompt":"A cat running in a garden"}\`
- Image-to-video → \`{"op":"create","image_url":"https://example.com/cat.jpg","prompt":"The cat runs forward"}\`
- Check task → \`{"op":"get","task_id":"<task_id from create>"}\`
工作流:\`create\` 调一次,然后反复用 \`get\` 查同一个 \`task_id\`,直到 status 变成 completed 或 failed。**不要为了看进度重复提交任务。**
耗时参考:minimax 约 2 分钟(扣 57 积分),kling 约 8 分钟(扣 103 积分)。视频直链约 12 小时失效。`,
Workflow: call \`create\` once, then call \`get\` with the returned \`task_id\` until status is \`completed\` or \`failed\`. Never create duplicate tasks just to check status.`,
{
op: z
.enum(["create", "get"])
.describe("create 提交生成;get 按 task_id 查结果。"),
op: z.enum(["create", "get"]).describe("create 提交生成;get 按 task_id 查结果。"),
prompt: z
.string()
.max(2000)
.optional()
.describe("视频描述,create 必填。图生视频时描述画面如何运动。"),
.describe("视频描述,create 时 prompt 与 image_url 至少给一个。图生视频时描述画面如何运动。"),
image_url: z
.string()
.url()
.optional()
.describe(
"图生视频的参考图,公网可访问的 png/jpeg URL。本地文件先用 mint_public_link 换成公网短链。"
"参考图(图生视频):公开可访问的 png/jpeg URL。本地文件先用 agent 内置的公开临时 URL 工具换成短链。"
),
seconds: z
.number()
.min(4)
.max(15)
.optional()
.describe("视频时长(秒),默认 4。越长越慢越贵。"),
aspect_ratio: z
.string()
.optional()
.describe("画幅,如 16:9 / 9:16 / 1:1。上游不严格校验,写合法值即可。"),
resolution: z
.string()
.optional()
.describe("分辨率,如 768P / 1080P。留空用上游默认。"),
negative_prompt: z
.string()
.optional()
.describe("不希望出现的画面描述。"),
enable_audio: z
.boolean()
.optional()
.describe("是否生成音频,默认 false。"),
with_audio: z
.boolean()
.optional()
.describe("旧字段名,等同 enable_audio。"),
task_id: z
.string()
.int()
.min(1)
.max(60)
.optional()
.describe("create 返回的 task_id,get 时必填。"),
.describe("视频时长(秒)。留空用上游默认;越长越慢越贵。"),
aspect_ratio: z.string().optional().describe("画幅,如 16:9 / 9:16 / 1:1。"),
resolution: z.string().optional().describe("分辨率,如 768P / 1080P。留空用上游默认。"),
negative_prompt: z.string().optional().describe("不希望出现的画面描述。"),
enable_audio: z.boolean().optional().describe("是否生成音频,默认 false。"),
with_audio: z.boolean().optional().describe("旧字段名,等同 enable_audio。"),
task_id: z.string().min(1).optional().describe("create 返回的 task_id,get 时必填。"),
},
async (args, extra) => {
const headers = extra?.requestInfo?.headers;
const token = pickToken(headers);
if (!token) {
return {
isError: true,
content: [{ type: "text", text: "缺少鉴权:header 里要带 Authorization: Bearer <API Key>。" }],
};
}
switch (args.op) {
case "create":
return await handleCreate({ args, headers, token });
return await handleCreate({ args, headers });
case "get":
return await handleGet({ args, token });
return await handleGet({ args, headers });
default:
return {
isError: true,
content: [{ type: "text", text: `未知 op "${args.op}"(可用:create、get)。` }],
content: [{ type: "text", text: `Unknown op "${args.op}" (available: create, get).` }],
};
}
}
@@ -384,19 +364,15 @@ async function startHttp({ port, host }) {
closeAllSessions = () => {
for (const { server, transport } of sessions.values()) {
try {
transport.close();
} catch {}
try {
server.close();
} catch {}
try { transport.close(); } catch {}
try { server.close(); } catch {}
}
sessions.clear();
httpServer?.closeAllConnections?.();
};
app.get("/health", (_req, res) => {
res.json({ status: "ok", service: "video_task", upstream: WB_BASE, sessions: sessions.size });
res.json({ status: "ok", service: "video_task", sessions: sessions.size });
});
async function handleSessionRequest(req, res) {
@@ -411,10 +387,7 @@ async function startHttp({ port, host }) {
if (!isInitializeRequest(req.body)) {
res.status(400).json({
jsonrpc: "2.0",
error: {
code: -32000,
message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request",
},
error: { code: -32000, message: "Bad Request: missing valid Mcp-Session-Id for non-initialize request" },
id: req.body?.id ?? null,
});
return;
@@ -424,15 +397,11 @@ async function startHttp({ port, host }) {
const server = buildServer();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => newId,
onsessioninitialized: (id) => {
sessions.set(id, { server, transport });
},
onsessioninitialized: (id) => { sessions.set(id, { server, transport }); },
});
transport.onclose = () => {
if (transport.sessionId) {
sessions.delete(transport.sessionId);
}
if (transport.sessionId) sessions.delete(transport.sessionId);
};
await server.connect(transport);
@@ -454,7 +423,7 @@ async function startHttp({ port, host }) {
app.delete("/mcp", handleOther);
httpServer = app.listen(port, host, () => {
console.log(`[video] MCP HTTP server listening on http://${host}:${port}/mcp → ${WB_BASE}`);
console.log(`[video] MCP HTTP server listening on http://${host}:${port}/mcp`);
});
}