aihubmix-image-mcp/README.md

MCP server for AIHUBMIX image generation with URL support (NANO BANANA)

# AIHUBMIX Image MCP Server（简明指南）

将 AIHUBMIX 的 NANO BANANA（Gemini 2.5 Flash Image）封装为 MCP 工具：
- generate_image（稳定）：文生图 / 图生图 / 多图编辑，支持 URL、本地路径、data URL、base64
- generate_video（实验）：两帧图片驱动 VEO-3 短视频（异步返回观看/下载链接）

要求
- Node.js ≥ 18

## 版本与推荐使用

- 稳定版（仅图片）：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 方式加载服务器，请按以下方式配置：

- command: "npx"
- args: ["-y", "aihubmix-image-mcp@3.0.0-beta.6"]
- env（必要/推荐）：
  - AIHUBMIX_API_KEY: sk- 开头的密钥（必填）
  - AIHUBMIX_OUTPUT_MODE: "url" | "file" | "summary" | "inlineBase64"
    - 如希望直接返回可访问链接，设为 "url"
  - AIHUBMIX_OUTPUT_DIR: 本地保存目录（回退到 file 时使用），如 "./generated-images"
  - AIHUBMIX_OUTPUT_PREVIEW_CHARS: summary 模式预览长度，默认 80
  - SUPABASE_URL: 你的 Supabase 项目 URL（如 https://xxxxx.supabase.co）
  - SUPABASE_ANON_KEY: 你的 Supabase 匿名密钥（需能向公共桶上传）
  - SUPABASE_BUCKET: "MATERIALS"（你已有的 PUBLIC 桶）
  - SUPABASE_PATH_PREFIX: "mcp/"（对象路径前缀，可选）

- timeout: 建议 >= 180000（图片一般够用；视频建议更长）

最小可用 env 示例（URL 输出）：
- AIHUBMIX_API_KEY=sk-xxxx
- AIHUBMIX_OUTPUT_MODE=url
- SUPABASE_URL=https://<project-ref>.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"

## 工具速览

1) generate_image（稳定）
- 用途：文生图、图生图、多图融合/风格迁移
- 入参：
  - 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）

2) generate_video（实验，veo-3）
- 用途：两帧图片（首帧/尾帧）+ 文本提示 → 短视频（异步）
- 入参：
  - 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-<timestamp>.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://<project-ref>.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）：
  - GET https://aihubmix.com/v1/models（携带 Authorization: Bearer ${AIHUBMIX_API_KEY}）
- 本仓库内置两帧测试脚本（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