video-gen: add /upload endpoint for local image upload

Adds POST /upload (multer diskStorage, max 8MB, image/* only) returning
a public URL under /uploads/* that can be passed directly to
generate_video.image_url. Uploads live in container temp storage and
are discarded on restart (no persistence, no auth).

generate_video tool description is now built at startup with the real
upload URL baked in (resolved from PUBLIC_BASE_URL env, falls back to
http://localhost:<port>) so the AI sees an exact curl command and
doesn't have to guess the host.

docker-compose: set PUBLIC_BASE_URL=https://video-gen.ai.foresh.com
README: new upload section, reverse-proxy note, FAQ entries
This commit is contained in:
2026-09-04 20:58:51 +08:00
parent 710200605b
commit e378ad001f
4 changed files with 209 additions and 28 deletions
+13 -12
View File
@@ -26,18 +26,19 @@ services:
- my-app-network
mcp-video-gen:
build: ./video-gen
container_name: mcp-video-gen
restart: unless-stopped
expose:
- "3000"
environment:
- VIRTUAL_HOST=video-gen.ai.foresh.com
- VIRTUAL_PORT=3000
- CERT_NAME=default
networks:
- my-app-network
build: ./video-gen
container_name: mcp-video-gen
restart: unless-stopped
expose:
- "3000"
environment:
- VIRTUAL_HOST=video-gen.ai.foresh.com
- VIRTUAL_PORT=3000
- CERT_NAME=default
- PUBLIC_BASE_URL=https://video-gen.ai.foresh.com
networks:
- my-app-network
networks:
my-app-network:
external: true
external: true
+96 -5
View File
@@ -7,6 +7,7 @@
- 默认模型:`cogvideox-flash`
- 端口:`3000`
- 鉴权:**无服务端密钥**,每次请求必须从 header 携带智谱 token
- 附带 `/upload` 端点:供 AI 临时上传本地图片获取 URL(**不持久化**,容器重启即丢)
---
@@ -64,6 +65,75 @@ curl http://localhost:3000/health
---
## 上传图片:POST /upload
供 AI 临时上传本地图片、拿到 URL 后喂给 `generate_video.image_url`。**不走 MCP、不走鉴权**,仅依赖内网隔离(`my-app-network`)+ 反代层控制访问。
### 配置
通过环境变量告诉服务端「对外公开的 base URL」,用于拼接返回的 `url` 字段:
```yaml
# docker-compose.yml
environment:
- PUBLIC_BASE_URL=https://video-gen.ai.foresh.com
```
未设置时 fallback 到 `http://localhost:3000`(本机调试)。
### 接口
```
POST /upload
Content-Type: multipart/form-data
file: <二进制图片文件>
```
### 限制
| 项 | 值 |
|---|---|
| 最大体积 | 8MB(智谱 `image_url` 上限5MB,留余量) |
| 白名单 content-type | `image/png`、`image/jpeg`、`image/jpg` |
| 存储位置 | 容器内 `/tmp/video-gen-uploads/`(`UPLOAD_DIR` 可覆盖) |
| 持久化 | **不持久化**。容器重启即丢,请尽快消费 URL |
| 鉴权 | 无 |
### 返回
```jsonc
{
"url": "https://video-gen.ai.foresh.com/uploads/abc123.png",
"filename": "abc123.png",
"size": 12345,
"content_type": "image/png",
"original_name": "my-cat.png"
}
```
返回的 `url` 可直接作为 `generate_video.image_url` 使用。
### 反代路由
反代需要额外暴露两条路由到 `mcp-video-gen:3000`:
- `POST /upload` → `/upload`
- `GET /uploads/*` → `/uploads/*`
### curl 示例
```bash
curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload
# {"url":"https://video-gen.ai.foresh.com/uploads/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png", ...}
# 然后把 url 喂给 MCP:
# tool: generate_video
# args: { image_url: "https://video-gen.ai.foresh.com/uploads/xxx.png", prompt: "..." }
```
---
## 工具:generate_video
提交一个视频生成任务,支持**文生视频**和**图生视频**。**至少**需要传 `prompt` 或 `image_url` 其中之一;两者都传也行(image-to-video 时 prompt 会被附加为运动/动作描述)。
@@ -156,14 +226,17 @@ Token 仅在每次 tool call 时从 header 读取,不写入任何存储、不
## 推荐用法(AI 视角)
```
1. AI 决定生成视频 → 调用 generate_video({ prompt, image_url?, size?, with_audio? })
2. 拿到 task_id → 等待若干秒(建议 2~5 秒)
3. 调用 query_video({ task_id })
1. 如果手头是【本地文件】:先调 POST {PUBLIC_BASE_URL}/upload 拿到 url,再进第 2 步
2. 调用 generate_video({ prompt, image_url?, size?, with_audio? })
3. 拿到 task_id → 等待若干秒(建议 2~5 秒)
4. 调用 query_video({ task_id })
- 若 PROCESSING → 等一会再调
- 若 SUCCESS → 拿到 video URL,贴给用户 / 下载 / 二次编辑
- 若 FAIL → 展示错误信息,结束
```
> `generate_video` 的 tool description 里已经嵌入了完整 curl 上传命令,AI 一看就知道怎么传本地图片。
---
## 用 curl 手工调试
@@ -247,6 +320,17 @@ curl -s -X POST http://localhost:3000/mcp \
响应是 SSE 格式(`event: message` + `data: {...}`),用 `grep '^data:'` 抽 JSON 即可。
### 单独调试 `/upload`
```bash
# 上传图片,返回 url
curl -F "file=@/tmp/cat.png" https://video-gen.ai.foresh.com/upload
# {"url":"https://video-gen.ai.foresh.com/uploads/xxx.png", ...}
# 下载上传过的文件
curl -o cat.png https://video-gen.ai.foresh.com/uploads/xxx.png
```
---
## 架构与文件
@@ -255,7 +339,7 @@ curl -s -X POST http://localhost:3000/mcp \
video-gen/
├── Dockerfile # node:22-slim,安装依赖后启动 MCP HTTP server
├── .dockerignore # 排除 node_modules
├── package.json # @modelcontextprotocol/sdk + express(无新依赖)
package.json # @modelcontextprotocol/sdk + express + multer
├── README.md # 本文件
└── src/
└── mcp-server.js # 单文件实现:HTTP server + MCP transport + 双工具
@@ -270,6 +354,7 @@ video-gen/
- `model / quality / fps / duration / watermark_enabled` 全部由 HTTP header 注入,避免 AI 误传或被诱导调高价档
- **异步语义暴露给 AI**:服务端不做轮询,`generate_video` 只提交、`query_video` 只查一次。AI 自主决定节奏
- **服务端自动 `request_id`**:每次提交服务端生成一个 UUID 作为智谱 `request_id`,便于日志关联,但不暴露给 AI
- **上传接口与 MCP 走同一进程**:额外 `POST /upload` + `GET /uploads/*` 不走 MCP、不鉴权,靠内网隔离;`PUBLIC_BASE_URL` 环境变量控制返回 URL 的拼接 host,AI 看到的 tool description 启动时拼接进真实地址,避免 AI 自由发挥
### 默认模型
@@ -303,4 +388,10 @@ A: 漏发了 `Mcp-Session-Id` header,或调 `tools/call` 前没先 `initialize
A: 可以。`/async-result/{id}` 是幂等的读接口,并发无副作用。
**Q: 换模型需要重连 MCP session 吗?**
A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。
A: 不需要。Model header 在每次 `tools/call` 都从当前请求读取。
**Q: 上传的图片多久过期?**
A: 容器重启即丢(本服务不持久化)。请在上传后立刻把返回的 `url` 喂给 `generate_video.image_url`。URL 本身只有可访问性,不受单独 TTL 限制;但容器一旦重启,该文件物理消失,URL 变 404。
**Q: `PUBLIC_BASE_URL` 不设会怎样?**
A: fallback 到 `http://localhost:3000`,AI 拿到的 curl 是 `http://localhost:3000/upload`。外网访问不到。本机调试无所谓,生产请显式设置。
+4 -3
View File
@@ -8,7 +8,8 @@
"start": "node src/mcp-server.js --http --port 3000 --host 0.0.0.0"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.4",
"express": "^4.21.0"
}
"@modelcontextprotocol/sdk": "^1.0.4",
"express": "^4.21.0",
"multer": "^1.4.5-lts.1"
}
}
+96 -8
View File
@@ -1,5 +1,8 @@
#!/usr/bin/env node
import express from "express";
import multer from "multer";
import path from "node:path";
import fs from "node:fs";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -20,6 +23,25 @@ const DEFAULT_FPS = 30; // 30 | 60
const DEFAULT_DURATION = 5; // 5 | 10
const DEFAULT_WATERMARK_ENABLED = true; // 平台政策默认 true
// ===== 上传文件相关 =====
// 公开的 base URL:拼接进 tool description,告诉 AI 该往哪里 POST 上传
// 优先级:环境变量 > 默认 http://localhost:<port>
function resolvePublicBaseUrl({ port, host }) {
const env = (process.env.PUBLIC_BASE_URL || "").trim();
if (env) return env.replace(/\/+$/, "");
return `http://localhost:${port}`;
}
// 上传文件存储目录:容器内临时目录,服务重启即丢(你明确要求)
const UPLOAD_DIR = process.env.UPLOAD_DIR || "/tmp/video-gen-uploads";
const UPLOAD_PATH_PREFIX = "/uploads"; // 对外的 URL 路径前缀
const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8MB(智谱 image_url 上限 5MB,留余量)
const UPLOAD_ALLOWED_MIME = new Set([
"image/png",
"image/jpeg",
"image/jpg",
]);
function parseArgs(argv) {
const args = {
http: false,
@@ -167,7 +189,7 @@ async function queryAsyncResult({ token, id }) {
return data; // { id, request_id, model, task_status, video_result?, ... }
}
function buildServer() {
function buildServer({ publicBaseUrl }) {
const server = new McpServer(
{
name: "video-gen",
@@ -180,12 +202,22 @@ function buildServer() {
}
);
const uploadUrl = `${publicBaseUrl}/upload`;
// ---------- 工具 1:generate_video ----------
server.tool(
"generate_video",
"Submit a video generation task (text-to-video or image-to-video) to Zhipu BigModel. " +
"Returns the task_id immediately; poll the result later with query_video. " +
"Provide prompt and/or image_url (at least one is required).",
`Submit a video generation task (text-to-video or image-to-video).
Returns the task_id immediately; poll the result later with query_video.
Provide prompt and/or image_url (at least one is required).
If you need to use a LOCAL image file as image_url, upload it FIRST with this exact command (replace the path):
curl -F "file=@/path/to/your/image.png" ${uploadUrl}
The response JSON has a "url" field — pass that URL directly as the image_url argument below.
Supported formats: png, jpeg, jpg. Max 5MB per image.
Uploaded files live in container temp storage and are discarded on restart — do not rely on long-term URLs.`,
{
prompt: z
.string()
@@ -197,7 +229,7 @@ function buildServer() {
.string()
.optional()
.describe(
"Reference image URL (or base64) for image-to-video. Supports up to 2 URLs for first/last frame. Image <= 5MB, .png/.jpeg/.jpg."
"Reference image source for image-to-video. String or Array of up to 2 URLs for first/last frame. Image <= 5MB, .png/.jpeg/.jpg."
),
size: z
.string()
@@ -379,6 +411,61 @@ async function startHttp({ port, host }) {
const app = express();
app.use(express.json({ limit: "2mb" }));
const publicBaseUrl = resolvePublicBaseUrl({ port, host });
console.log(`[video-gen] PUBLIC_BASE_URL = ${publicBaseUrl}`);
// ===== /upload:接收图片,返回 URL(不走 MCP)=====
// 磁盘存储:保证 UPLOAD_DIR 存在(容器内临时,重启即丢)
fs.mkdirSync(UPLOAD_DIR, { recursive: true });
const storage = multer.diskStorage({
destination: (_req, _file, cb) => cb(null, UPLOAD_DIR),
filename: (_req, file, cb) => {
const ext = (path.extname(file.originalname) || ".bin").toLowerCase();
cb(null, `${randomUUID()}${ext}`);
},
});
const upload = multer({
storage,
limits: { fileSize: UPLOAD_MAX_BYTES, files: 1 },
fileFilter: (_req, file, cb) => {
if (UPLOAD_ALLOWED_MIME.has(file.mimetype)) return cb(null, true);
cb(new Error(`Unsupported content-type: ${file.mimetype}. Allowed: ${[...UPLOAD_ALLOWED_MIME].join(", ")}`));
},
});
app.post("/upload", (req, res) => {
upload.single("file")(req, res, (err) => {
if (err) {
const status = err.code === "LIMIT_FILE_SIZE" ? 413 : 400;
return res.status(status).json({
error: err.message || "upload failed",
});
}
if (!req.file) {
return res.status(400).json({ error: "Missing form field 'file'" });
}
const url = `${publicBaseUrl}${UPLOAD_PATH_PREFIX}/${req.file.filename}`;
return res.json({
url,
filename: req.file.filename,
size: req.file.size,
content_type: req.file.mimetype,
original_name: req.file.originalname,
});
});
});
// 静态下载:只要文件存在于 UPLOAD_DIR 就吐出去(不鉴权、不持久化)
app.use(
UPLOAD_PATH_PREFIX,
express.static(UPLOAD_DIR, {
fallthrough: false,
maxAge: 0,
})
);
// session -> { server, transport } 映射
const sessions = new Map();
@@ -410,7 +497,7 @@ async function startHttp({ port, host }) {
}
const newId = randomUUID();
const server = buildServer();
const server = buildServer({ publicBaseUrl });
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => newId,
onsessioninitialized: (id) => {
@@ -452,7 +539,8 @@ async function startHttp({ port, host }) {
}
async function startStdio() {
const server = buildServer();
// stdio 模式下上传接口不可用,用 placeholder 避免 description 里出现奇怪的占位
const server = buildServer({ publicBaseUrl: "http://localhost:3000" });
const { StdioServerTransport } = await import(
"@modelcontextprotocol/sdk/server/stdio.js"
);
@@ -472,4 +560,4 @@ if (args.http) {
console.error("[video-gen] failed to start stdio server:", e);
process.exit(1);
});
}
}