admin/Gemini_Draw

Fork 0

Files

admin e9df9cac06 finish api and docs validation fixes

2026-05-09 18:47:19 +08:00

6.4 KiB

Raw Blame History

API 图片绘制及修改 Agent 调用说明

本服务提供一个本地 HTTP API，用于让其他 Agent、脚本或自动化系统按文字指令绘制图片，或上传已有图片/文档并进一步修改、分析。

默认地址：

本机：http://localhost:3002
局域网：http://192.168.31.204:3002

必须携带 API 访问密钥

所有受保护接口都需要 API 访问密钥。这个密钥不是 Gemini API Key，而是本服务自己的调用密钥，用来防止局域网内其他人随意调用你的接口。

在服务端 .env.local 中配置：

API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"

调用时二选一携带：

Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN

或：

x-api-key: YOUR_LONG_RANDOM_API_TOKEN

如果没有配置 API_AUTH_TOKEN，/api/generate、/api/edit-image、/api/analyze-document、/api/config/* 等接口会拒绝请求。只在本机临时开发时，才可以设置：

API_AUTH_DISABLED="true"

Gemini API Key

Gemini API Key 有三种传入方式，按优先级从高到低：

单次请求 Header：x-gemini-api-key: YOUR_GEMINI_API_KEY
单次请求 JSON/Form 字段：apiKey=YOUR_GEMINI_API_KEY
服务端环境变量：.env.local 中的 GEMINI_API_KEY

运行中更新服务端 Gemini Key：

curl -X POST http://localhost:3002/api/config/api-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -d "{\"apiKey\":\"YOUR_GEMINI_API_KEY\",\"persist\":true}"

persist:true 会写入本项目的 .env.local，该文件不会提交到 git。

健康检查

curl http://localhost:3002/api/health

返回示例：

{
  "ok": true,
  "apiPort": 3002,
  "hasGeminiApiKey": true,
  "authEnabled": true,
  "authRequired": true,
  "acceptsPerRequestApiKey": true
}

修改已有图片

使用 multipart/form-data 上传图片，字段名可以叫 files、image 或任意名称；服务会读取所有上传文件。

curl -X POST http://localhost:3002/api/edit-image \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -F "prompt=保留主体不变，把背景改成干净的白色摄影棚，增强产品质感" \
  -F "imageSize=1K" \
  -F "aspectRatio=1:1" \
  -F "files=@input.png"

支持的图片常见格式：

image/png
image/jpeg
image/webp

可选参数：

prompt 或 instruction：修改指令，必填
imageSize：1K、2K、4K，默认 1K
aspectRatio：1:1、4:3、3:4、16:9、9:16，默认 1:1
model：默认 gemini-3.1-flash-image-preview
apiKey：单次调用使用的 Gemini API Key

成功响应示例：

{
  "ok": true,
  "model": "gemini-3.1-flash-image-preview",
  "images": [
    {
      "mimeType": "image/png",
      "data": "BASE64_IMAGE_DATA",
      "dataUrl": "data:image/png;base64,BASE64_IMAGE_DATA"
    }
  ],
  "texts": []
}

调用方可以直接使用 images[0].dataUrl 预览图片，或把 images[0].data 解码保存为 PNG 文件。

纯文字绘制图片

不上传图片时，直接用 prompt 生成新图片：

curl -X POST http://localhost:3002/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -d "{\"prompt\":\"画一个蓝天白云下的极简风景插画\",\"imageSize\":\"1K\",\"aspectRatio\":\"1:1\"}"

JSON/Base64 方式修改图片

如果 Agent 已经拿到了图片 base64，可以不用 multipart：

curl -X POST http://localhost:3002/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -d "{
    \"prompt\":\"把这张图改成赛博朋克夜景风格，但保留人物脸部特征\",
    \"imageSize\":\"1K\",
    \"aspectRatio\":\"1:1\",
    \"images\":[
      {
        \"mimeType\":\"image/png\",
        \"base64\":\"BASE64_IMAGE_DATA\"
      }
    ]
  }"

也可以传 dataUrl：

{
  "prompt": "把背景改成浅灰色",
  "images": [
    {
      "dataUrl": "data:image/png;base64,BASE64_IMAGE_DATA"
    }
  ]
}

或传公开可访问 URL：

{
  "prompt": "生成一张更适合电商首图的版本",
  "images": [
    {
      "url": "https://example.com/input.png"
    }
  ]
}

上传文档分析

用于 PDF、Word 转出的文本文件、图片文档等分析任务。这个接口默认使用文本模型。

curl -X POST http://localhost:3002/api/analyze-document \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -F "prompt=用中文总结这份文档，提取关键结论和待办事项" \
  -F "files=@report.pdf"

响应中的 texts 是模型返回的文字结果：

{
  "ok": true,
  "model": "gemini-2.5-flash",
  "texts": ["文档总结内容..."],
  "images": []
}

多文件输入

一个请求可以同时上传多张图片或多个文档：

curl -X POST http://localhost:3002/api/edit-image \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -F "prompt=参考第二张图的色调，修改第一张图" \
  -F "files=@source.png" \
  -F "files=@style-reference.jpg"

错误格式

失败时统一返回：

{
  "ok": false,
  "error": "错误原因"
}

常见错误：

Unauthorized. Send Authorization: Bearer YOUR_API_AUTH_TOKEN or x-api-key.：缺少 API 访问密钥
API_AUTH_TOKEN is required.：服务端没有配置 API 访问密钥
prompt or instruction is required.：缺少修改指令
Gemini API key is required.：没有配置或传入 Gemini API Key
Remote file is too large.：URL 文件超过大小限制

Agent 调用建议

每次调用都必须带 Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN 或 x-api-key。
Gemini Key 建议用 x-gemini-api-key 单次传入，避免依赖服务端环境。
优先使用 POST /api/edit-image + multipart 上传真实图片文件。
如果图片已经是 base64，使用 POST /api/generate 的 images[].base64。
取返回的 images[0].dataUrl 给用户预览；保存文件时解码 images[0].data。
修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。

6.4 KiB Raw Blame History Unescape Escape