generateImage — 腾讯云开发（CloudBase）AI 生图云函数

一个可直接部署的 CloudBase 云函数，把混元生图封装成两种形态：

1. HTTP 接口 —— 文生图 / 图生图，带 API Key 鉴权与真实 HTTP 状态码

2. MCP Server —— 可直接接入 Claude Code / Cursor 等标准 MCP 客户端

同时提供一份零框架自建版（selfhosted/），同一套核心逻辑可脱离云函数在普通 Node 进程运行。

特性

Related MCP server: mcp-image

目录结构

.
├── index.js              # 云函数主逻辑（单文件，无外部框架依赖）
├── package.json          # 依赖：@cloudbase/node-sdk + sharp
├── CONVENTIONS.md        # ★ 文档与密钥约定（改文档前先读）
├── docs/实测报告.md       # ★ 完整技术文档：能力 / 实测 / 踩坑 / 调用示例
├── test/                 # 离线单测（自带 SDK 替身，无需 npm install）
└── selfhosted/           # 可脱离云函数运行的自建版
    ├── server.js         #   零框架，仅用 Node 内置 http 模块
    ├── package.json
    ├── README.md         #   迁移说明：哪些要改、凭证怎么传、差异清单
    └── test/

快速开始（云函数）

1. 部署

# 依赖 sharp（含原生绑定）建议用云函数层挂载，代码包内不要带 node_modules
# 详见 docs/实测报告.md 第十节

部署后在函数配置里设置环境变量：

2. 调用

curl -X POST "https://YOUR_ENV_ID-YOUR_APPID.ap-shanghai.app.tcloudbase.com/api/gen-image" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"prompt":"一只戴着宇航头盔的柴犬，赛博朋克风格","size":"1024x1024"}'

3. 接入 MCP 客户端

{
  "mcpServers": {
    "generate-image": {
      "type": "http",
      "url": "https://YOUR_ENV_ID-YOUR_APPID.ap-shanghai.app.tcloudbase.com/api/gen-image?mcp=1",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

type 必填 —— 只有 url 没有 type 会被客户端当作 stdio 传输，报错。

快速开始（自建版，不用云函数）

cd selfhosted
npm install

CLOUDBASE_ENV=YOUR_ENV_ID \
TENCENTCLOUD_SECRETID=xxx \
TENCENTCLOUD_SECRETKEY=xxx \
API_KEY=your-api-key \
node server.js

接口与云函数版完全一致，客户端无需改动。差异与注意事项见 selfhosted/README.md。

临时密钥必须同时传 sessionToken，否则报 HTTP 401。长期密钥（CAM 生成）不需要。

这个项目踩过的坑（都写进文档了）

docs/实测报告.md 是本仓库最有价值的部分，记录了实测过程中发现的真实问题：

• ★ ai.createImageModel(X) 的第一个参数是 provider，不是模型名 —— 传错必 404（本项目最大的坑）

• ★ CloudBase HTTP 网关只返回普通对象时一律回 HTTP 200 —— 错误分支必须返回带 statusCode 的结构才能透传真实状态码

• ★ MCP 鉴权：只有 tools/call 该校验 key —— initialize / ping / notifications/* 等协议层方法必须放行，否则标准客户端连不上

• ★ 用「字段是否为空」判断请求通道是不可靠的 —— 曾因此让普通 HTTP 请求整个绕过鉴权

• ★ sharp 在 CloudBase 上必须用云函数层挂载 —— 本地 node_modules 会被打包上传，平台不匹配导致 require 失败

环境要求

• Node.js 18+（云函数运行时 Nodejs18.15）

• @cloudbase/node-sdk >= 3.18.3（2.x 没有 ai() 方法，会报 app.ai is not a function）

• sharp ^0.33.5

持续集成

仓库自带 GitHub Actions 工作流 .github/workflows/ci.yml，在 push / PR 到 main 时自动执行：

设计取舍：

• 刻意不做 npm install —— 本仓库依赖 sharp（含原生绑定）和 @cloudbase/node-sdk，在 CI 装它意义不大（真正的运行环境是云函数层挂载的 sharp），且会拖慢流水线。单测自带 SDK 替身，所以照样能跑。

• 敏感信息扫描是防回归的，不是替代人工审计 —— 仓库是公开的，任何一次 git push 前都会被这道门拦住。

• 三个 Node 版本覆盖了「云函数运行时 18.15」到「最新 LTS」，跨版本语法差异（如较新的内置 API）能被提前发现。

本地想跑同样的检查：

npm run check   # 语法
npm test        # 单测

频率限制

API Key 是一串长期不变的静态密钥，一旦泄露就是无限额度；而每次生成都真实消耗混元计费。 所以除鉴权外还做了一层限流：

• 只对消耗额度的调用计数 —— 普通 HTTP 生成与 MCP tools/call。 initialize / ping / notifications/* 等协议层方法不计数，否则客户端握手/探活就把配额吃光。

• 命中时：普通 HTTP 回 429 + Retry-After；MCP 回 JSON-RPC -32029（不是 -32001，避免把排查方向带偏到凭证问题）。

• 限流键是 API Key 的 SHA-256 指纹前 16 位，内存里不留明文。

⚠️ 已知局限：云函数版是实例内存态，多实例并发时实际阈值 ≈ 阈值 × 实例数。 需要严格全局限流时，应把 rateCheck() 的记账换成 Redis 或云数据库计数。 自建版（selfhosted/）是长驻进程，内存态即全局，限流是精确的。

测试

单测是离线的 —— 自带 @cloudbase/node-sdk 替身，无需 npm install、无凭证、无网络：

npm test                              # 全部
node test/index.test.js               # 云函数版：鉴权 / MCP 协议 / 状态码 / 水印 / size
node test/rate-limit.test.js          # 限流：滑动窗口 / 两层配额 / 协议层豁免
node selfhosted/test/server.test.js   # 自建版：鉴权 / 限流 / 状态码映射

限流测试通过劫持 Date.now 推进虚拟时间，无需真的 sleep 60 秒就能验证窗口滑动。

License

MIT