AIHUBMIX Image MCP Server（简明指南）
将 AIHUBMIX 的 NANO BANANA（Gemini 2.5 Flash Image）封装为 MCP 工具：
- generate_image（稳定）：文生图 / 图生图 / 多图编辑，支持 URL、本地路径、data URL、base64
- generate_video（实验）：两帧图片驱动 VEO-3 短视频（异步返回观看/下载链接）
要求
版本与推荐使用
- 稳定版（仅图片）：2.1.9
- 生产建议：使用 2.1.9（图片默认保存为文件，鲁棒性更高）
- Beta（含视频实验）：3.0.0-beta.6
- 需要视频时使用；在检测到 .mp4 链接且 Content-Type 为 mp4 时自动下载保存，否则返回链接文本
安装/接入（MCP 客户端以 npx 方式）
- 图片（稳定）使用 2.1.9
- args: ["-y", "aihubmix-image-mcp@2.1.9"]
- 图片 + 视频（Beta）使用 3.0.0-beta.6
- args: ["-y", "aihubmix-image-mcp@3.0.0-beta.6"]
环境变量（建议在 MCP 配置中设置 env）
- AIHUBMIX_API_KEY: sk- 开头的密钥（必填）
- AIHUBMIX_OUTPUT_MODE: 默认输出模式（图片工具），file | summary | inlineBase64，默认为 file
- AIHUBMIX_OUTPUT_DIR: 默认保存目录（建议绝对路径）
- AIHUBMIX_OUTPUT_PREVIEW_CHARS: summary 预览长度（默认 80）
- 可设置超时 timeout: 建议 ≥ 180000（视频较慢）
示例（仅作参考，按你的 MCP 客户端格式填入）
- 稳定版（图片）:
- command: "npx"
- args: ["-y", "aihubmix-image-mcp@2.1.9"]
- env: { AIHUBMIX_API_KEY, AIHUBMIX_OUTPUT_MODE: "file", AIHUBMIX_OUTPUT_DIR: "/ABS/PATH/generated-images" }
- timeout: 180000
- Beta（视频）:
- args: ["-y", "aihubmix-image-mcp@3.0.0-beta.6"]
- 其他同上；图片输出目录也可沿用
MCP 配置方法（重要）
如果你的 MCP 客户端支持以 npx 方式加载服务器，请按以下方式配置：
最小可用 env 示例（URL 输出）：
- AIHUBMIX_API_KEY=sk-xxxx
- AIHUBMIX_OUTPUT_MODE=url
- SUPABASE_URL=https://.supabase.co
- SUPABASE_ANON_KEY=xxxx
- SUPABASE_BUCKET=MATERIALS
- SUPABASE_PATH_PREFIX=mcp/
客户端调用 generate_image 示例：
- prompt: "A cute anime girl with blue hair"
- output: { "mode": "url", "filename": "demo.png" }
返回内容将包含 url=... 的公开链接；若上传失败或未配置 Supabase，则自动回退 file 并返回本地路径。
可选：全局安装
- npm i -g aihubmix-image-mcp
- MCP 中把 command 改为 "aihubmix-image-mcp"
工具速览
- 用途：文生图、图生图、多图融合/风格迁移
- 入参：
- prompt: string
- images?: Array<{ type: "image"; data: string; mimeType?: string }>
- data 支持 http/https、本地绝对路径、data:image/...、原始 base64
- output?（仅图片工具生效）：
- mode: "file" | "summary" | "inlineBase64"（默认 file）
- dir: 保存目录（默认 ./generated-images 或 AIHUBMIX_OUTPUT_DIR）
- filename: 文件名
- previewChars: summary 预览长度
- 返回：
- file：文本提示 + 文件已保存（包含路径与字节数）
- summary：文本提示 + base64 前缀预览
- inlineBase64：文本提示 + 纯 base64 图像数据
最小用法：
- prompt: "A cute anime girl with blue hair, kawaii style"
- images: 省略（纯文生图）
- 推荐 output.mode=file（默认会保存到 AIHUBMIX_OUTPUT_DIR 或 ./generated-images）
- 用途：两帧图片（首帧/尾帧）+ 文本提示 → 短视频（异步）
- 入参：
- prompt: string（可写时长/帧率/风格/BGM，例如“3–4 秒、24fps、史诗战歌 BGM、镜头自然过渡”）
- inputs?: Array<{ type: "image" | "video"; data: string; mimeType?: string }>
- 常见：两张图片作为首尾帧；建议大小 <= 20MB
- data 支持 http/https、本地绝对路径、data URL、原始 base64
- 返回：
- 当 output.mode=file 且检测到 .mp4 链接、响应 Content-Type 为 video/mp4 时：自动下载保存到本地（返回文本包含保存路径/大小，以及原始文本与链接）
- 否则：返回文本 + urls（包含 Watch/Download 等链接）
- 说明：
- 本工具会把图片转换为 data URL（image_url 形式）上传，以提升“严格使用两帧”的稳定性
- 上游为异步任务，如暂未返回直接 MP4 链接，则仅返回链接文本
最小用法（两帧转视频）：
- inputs:
- { type: "image", data: "/ABS/PATH/first.jpg", mimeType: "image/jpeg" }
- { type: "image", data: "/ABS/PATH/last.png", mimeType: "image/png" }
- prompt: "Create a 3–4s video transitioning from first to last image, 24fps, natural camera motion, epic battle anthem BGM."
提示：如仍出现“两帧未被严格使用”，可尝试压缩图片、确保主体清晰、在提示中强调“strictly use the provided two frames”，必要时多次重试。
输出与保存
- 图片（generate_image）默认以 file 模式落盘：
- 目录优先级：output.dir > AIHUBMIX_OUTPUT_DIR > ./generated-images
- 新增：url 模式（需 Supabase 环境变量）
- 当 output.mode = "url" 或 AIHUBMIX_OUTPUT_MODE = "url" 时：
- 从环境读取 SUPABASE_URL、SUPABASE_ANON_KEY、SUPABASE_BUCKET（默认 MATERIALS）、SUPABASE_PATH_PREFIX（默认 mcp/）
- 将生成图片以 objectKey = mcp/ai-image-.png 上传到指定桶
- 返回公开访问 URL（要求桶为 Public；你提供的 MATERIALS 已是 Public）
- 失败回退：若未配置或上传失败，自动回退为 file 模式落盘并返回路径与字节数提示
- 视频（generate_video）在 file 模式下：
- 仅当检测到 .mp4 链接且下载响应 Content-Type 为 video/mp4 时才会写入本地
- 目录优先级：output.dir > AIHUBMIX_OUTPUT_DIR > ./generated-videos
- inlineBase64 不适用于视频（体积与传输不合适）
快速排错
- 401 Unauthorized
- 多为 AIHUBMIX_API_KEY 未生效；请在 MCP 的 env 设置，或在同一终端 export 后再启动客户端
- 视频等待/无直链
- VEO-3 为异步长任务，可能排队或仅返回观看/下载页面链接。请稍后重试，或直接使用返回的 Watch/Download 链接查看
- 两帧未被“严格使用”
- 压缩图片、保证主体突出；在 prompt 中明确“strictly use two frames”；多次重试
- 保存目录
- 建议使用绝对路径；npx 方式默认相对路径会落在包目录下
环境变量（本地与 MCP 配置）
- AIHUBMIX_API_KEY=sk-...（必填）
- AIHUBMIX_OUTPUT_MODE=url | file | summary | inlineBase64（图片工具默认 file；你可以设为 url）
- AIHUBMIX_OUTPUT_DIR=./generated-images（文件回退/保存目录）
- AIHUBMIX_OUTPUT_PREVIEW_CHARS=80
- SUPABASE_URL=https://.supabase.co
- SUPABASE_ANON_KEY=xxxxx
- SUPABASE_BUCKET=MATERIALS（你现有的 Public 桶）
- SUPABASE_PATH_PREFIX=mcp/
端到端示例（url 输出）：
- 在运行环境设置上述变量（或把 .env.local 映射到 MCP）
- 调用 generate_image：
- prompt: "A cute anime girl with blue hair"
- output: { "mode": "url", "filename": "demo.png" }（可选）
- 返回：文本中包含 url=... 的公开链接
自检与测试
- 快速连通性（应返回 200）：
- 本仓库内置两帧测试脚本（Node）：
- cd aihubmix-image-mcp-simple
- node TEST/test-veo3-frames.mjs
未来计划
- 提示词模版（Prompt Templates，计划中）
- 预期新增请求字段：template、templateId、variables
- 渲染优先级：template/templateId 渲染结果 > 直接 prompt
- 变量缺失给出警告但不阻塞
- 内置少量模板并支持扩展
- 文档将提供示例与校验策略
版本策略（简）
- 2.1.9：稳定图片工具（默认文件落盘、鲁棒解析、清晰错误）
- 3.0.0-beta.6：generate_video 增加回退；当未检测到直链且文本包含上传错误提示时，自动调用 /v1/responses（input_text + input_image）重试；仍保留 MP4 下载内容类型校验
许可证
MIT
