add api key settings and agent docs
This commit is contained in:
208
API图片修改-Agent.md
Normal file
208
API图片修改-Agent.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# API 图片修改 Agent 调用说明
|
||||
|
||||
本服务提供一个本地 HTTP API，用于让其他 Agent、脚本或自动化系统上传已有图片/文档，并按文字指令生成或修改图片。
|
||||
|
||||
默认地址：
|
||||
|
||||
- 本机：`http://localhost:3002`
|
||||
- 局域网：`http://192.168.31.204:3002`
|
||||
|
||||
## 认证与 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`
|
||||
|
||||
运行中更新服务端 Key：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/config/api-key \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"apiKey\":\"YOUR_GEMINI_API_KEY\",\"persist\":true}"
|
||||
```
|
||||
|
||||
`persist:true` 会写入本项目的 `.env.local`，该文件不会提交到 git。
|
||||
|
||||
如果服务设置了 `API_AUTH_TOKEN`，还需要在每次请求中加入：
|
||||
|
||||
```txt
|
||||
Authorization: Bearer YOUR_API_AUTH_TOKEN
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```txt
|
||||
x-api-key: YOUR_API_AUTH_TOKEN
|
||||
```
|
||||
|
||||
## 健康检查
|
||||
|
||||
```bash
|
||||
curl http://localhost:3002/api/health
|
||||
```
|
||||
|
||||
返回示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"apiPort": 3002,
|
||||
"hasGeminiApiKey": true,
|
||||
"authEnabled": false,
|
||||
"acceptsPerRequestApiKey": true
|
||||
}
|
||||
```
|
||||
|
||||
## 修改已有图片
|
||||
|
||||
使用 `multipart/form-data` 上传图片，字段名可以叫 `files`、`image` 或任意名称；服务会读取所有上传文件。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/edit-image \
|
||||
-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 "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 "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 "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
|
||||
-F "prompt=参考第二张图的色调，修改第一张图" \
|
||||
-F "files=@source.png" \
|
||||
-F "files=@style-reference.jpg"
|
||||
```
|
||||
|
||||
## 错误格式
|
||||
|
||||
失败时统一返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": "错误原因"
|
||||
}
|
||||
```
|
||||
|
||||
常见错误：
|
||||
|
||||
- `prompt or instruction is required.`：缺少修改指令
|
||||
- `Gemini API key is required.`：没有配置或传入 Gemini API Key
|
||||
- `Remote file is too large.`：URL 文件超过大小限制
|
||||
|
||||
## Agent 调用建议
|
||||
|
||||
1. 优先使用 `POST /api/edit-image` + multipart 上传真实图片文件。
|
||||
2. 如果图片已经是 base64，使用 `POST /api/generate` 的 `images[].base64`。
|
||||
3. 每次调用都带 `x-gemini-api-key`，可避免依赖服务端环境。
|
||||
4. 取返回的 `images[0].dataUrl` 给用户预览；保存文件时解码 `images[0].data`。
|
||||
5. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。
|
||||
Reference in New Issue
Block a user