234 lines
6.0 KiB
Markdown
234 lines
6.0 KiB
Markdown
# API 图片修改 Agent 调用说明
|
||
|
||
本服务提供一个本地 HTTP API，用于让其他 Agent、脚本或自动化系统上传已有图片/文档，并按文字指令生成或修改图片。
|
||
|
||
默认地址：
|
||
|
||
- 本机：`http://localhost:3002`
|
||
- 局域网：`http://192.168.31.204:3002`
|
||
|
||
## 必须携带 API 访问密钥
|
||
|
||
所有受保护接口都需要 API 访问密钥。这个密钥不是 Gemini API Key，而是本服务自己的调用密钥，用来防止局域网内其他人随意调用你的接口。
|
||
|
||
在服务端 `.env.local` 中配置：
|
||
|
||
```env
|
||
API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"
|
||
```
|
||
|
||
调用时二选一携带：
|
||
|
||
```txt
|
||
Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN
|
||
```
|
||
|
||
或：
|
||
|
||
```txt
|
||
x-api-key: YOUR_LONG_RANDOM_API_TOKEN
|
||
```
|
||
|
||
如果没有配置 `API_AUTH_TOKEN`，`/api/generate`、`/api/edit-image`、`/api/analyze-document`、`/api/config/*` 等接口会拒绝请求。只在本机临时开发时，才可以设置：
|
||
|
||
```env
|
||
API_AUTH_DISABLED="true"
|
||
```
|
||
|
||
## Gemini API Key
|
||
|
||
Gemini API Key 有三种传入方式，按优先级从高到低：
|
||
|
||
1. 单次请求 Header：`x-gemini-api-key: YOUR_GEMINI_API_KEY`
|
||
2. 单次请求 JSON/Form 字段：`apiKey=YOUR_GEMINI_API_KEY`
|
||
3. 服务端环境变量：`.env.local` 中的 `GEMINI_API_KEY`
|
||
|
||
运行中更新服务端 Gemini Key：
|
||
|
||
```bash
|
||
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。
|
||
|
||
## 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:3002/api/health
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"apiPort": 3002,
|
||
"hasGeminiApiKey": true,
|
||
"authEnabled": true,
|
||
"authRequired": true,
|
||
"acceptsPerRequestApiKey": true
|
||
}
|
||
```
|
||
|
||
## 修改已有图片
|
||
|
||
使用 `multipart/form-data` 上传图片，字段名可以叫 `files`、`image` 或任意名称；服务会读取所有上传文件。
|
||
|
||
```bash
|
||
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
|
||
|
||
成功响应示例：
|
||
|
||
```json
|
||
{
|
||
"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 文件。
|
||
|
||
## JSON/Base64 方式修改图片
|
||
|
||
如果 Agent 已经拿到了图片 base64，可以不用 multipart：
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```json
|
||
{
|
||
"prompt": "把背景改成浅灰色",
|
||
"images": [
|
||
{
|
||
"dataUrl": "data:image/png;base64,BASE64_IMAGE_DATA"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
或传公开可访问 URL：
|
||
|
||
```json
|
||
{
|
||
"prompt": "生成一张更适合电商首图的版本",
|
||
"images": [
|
||
{
|
||
"url": "https://example.com/input.png"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 上传文档分析
|
||
|
||
用于 PDF、Word 转出的文本文件、图片文档等分析任务。这个接口默认使用文本模型。
|
||
|
||
```bash
|
||
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` 是模型返回的文字结果：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"model": "gemini-2.5-flash",
|
||
"texts": ["文档总结内容..."],
|
||
"images": []
|
||
}
|
||
```
|
||
|
||
## 多文件输入
|
||
|
||
一个请求可以同时上传多张图片或多个文档：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
## 错误格式
|
||
|
||
失败时统一返回：
|
||
|
||
```json
|
||
{
|
||
"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 调用建议
|
||
|
||
1. 每次调用都必须带 `Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN` 或 `x-api-key`。
|
||
2. Gemini Key 建议用 `x-gemini-api-key` 单次传入，避免依赖服务端环境。
|
||
3. 优先使用 `POST /api/edit-image` + multipart 上传真实图片文件。
|
||
4. 如果图片已经是 base64，使用 `POST /api/generate` 的 `images[].base64`。
|
||
5. 取返回的 `images[0].dataUrl` 给用户预览；保存文件时解码 `images[0].data`。
|
||
6. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。
|