140 lines
4.5 KiB
Markdown
140 lines
4.5 KiB
Markdown
# API 图片绘制及修改 Agent 调用说明 NAS 版
|
||
|
||
本文件用于部署在 NAS 上的 Gemini Draw。默认 NAS 服务地址：
|
||
|
||
- 前端页面：`http://192.168.31.5:4001`
|
||
- API 地址：`http://192.168.31.5:4000`
|
||
- 健康检查：`http://192.168.31.5:4000/api/health`
|
||
|
||
NAS 专用包 `Gemini_Draw_nas_gemini-drawpicture.zip` 已适配路径：
|
||
|
||
```txt
|
||
/share/Container/gemini-drawpicture
|
||
```
|
||
|
||
Container Station 创建应用时不要再使用相对环境文件路径。NAS 版 `docker_compose_Nas.yaml` 已把变量写在 `environment` 中，避免出现 `/tmp/.env.local not found`。
|
||
|
||
## 必须携带 API 访问密钥
|
||
|
||
所有受保护接口都需要 API 访问密钥。这个密钥不是 Gemini API Key，而是本服务自己的调用密钥。
|
||
|
||
调用时二选一携带：
|
||
|
||
```txt
|
||
Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN
|
||
```
|
||
|
||
或：
|
||
|
||
```txt
|
||
x-api-key: YOUR_LONG_RANDOM_API_TOKEN
|
||
```
|
||
|
||
## Gemini API Key
|
||
|
||
Gemini API Key 可以通过三种方式提供：
|
||
|
||
1. 已在 NAS 版 `docker_compose_Nas.yaml` 的 `environment.GEMINI_API_KEY` 中配置。
|
||
2. 单次请求 Header：`x-gemini-api-key: YOUR_GEMINI_API_KEY`
|
||
3. 单次请求 JSON/Form 字段：`apiKey=YOUR_GEMINI_API_KEY`
|
||
|
||
运行中更新服务端 Gemini Key：
|
||
|
||
```bash
|
||
curl -X POST http://192.168.31.5:4000/api/config/api-key \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
|
||
-d "{\"apiKey\":\"YOUR_GEMINI_API_KEY\",\"persist\":false}"
|
||
```
|
||
|
||
NAS 的 Container Station 场景建议把固定 Key 写在 `docker_compose_Nas.yaml` 的 `environment` 中，然后重建容器；`persist:true` 主要用于普通本地运行。
|
||
|
||
## 健康检查
|
||
|
||
```bash
|
||
curl http://192.168.31.5:4000/api/health
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"apiPort": 3002,
|
||
"hasGeminiApiKey": true,
|
||
"authEnabled": true,
|
||
"authRequired": true,
|
||
"acceptsPerRequestApiKey": true
|
||
}
|
||
```
|
||
|
||
## 纯文字绘制图片
|
||
|
||
```bash
|
||
curl -X POST http://192.168.31.5:4000/api/generate \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
|
||
-d "{\"prompt\":\"画一个蓝天白云下的极简风景插画\",\"imageSize\":\"1K\",\"aspectRatio\":\"1:1\"}"
|
||
```
|
||
|
||
PowerShell 保存返回图片：
|
||
|
||
```powershell
|
||
$token='YOUR_LONG_RANDOM_API_TOKEN'; $body=@{prompt='画一个蓝天白云下的极简风景插画'; imageSize='1K'; aspectRatio='1:1'} | ConvertTo-Json -Depth 5; $r=Invoke-RestMethod -Uri 'http://192.168.31.5:4000/api/generate' -Method Post -Headers @{Authorization="Bearer $token"} -ContentType 'application/json; charset=utf-8' -Body $body; [IO.File]::WriteAllBytes((Join-Path (Get-Location) 'nas-output.png'), [Convert]::FromBase64String($r.images[0].data))
|
||
```
|
||
|
||
## 修改已有图片
|
||
|
||
```bash
|
||
curl -X POST http://192.168.31.5:4000/api/edit-image \
|
||
-H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
|
||
-F "prompt=保留主体不变，把背景改成干净的白色摄影棚，增强产品质感" \
|
||
-F "imageSize=1K" \
|
||
-F "aspectRatio=1:1" \
|
||
-F "files=@input.png"
|
||
```
|
||
|
||
## 上传文档分析
|
||
|
||
```bash
|
||
curl -X POST http://192.168.31.5:4000/api/analyze-document \
|
||
-H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
|
||
-F "prompt=用中文总结这份文档，提取关键结论和待办事项" \
|
||
-F "files=@report.pdf"
|
||
```
|
||
|
||
## JSON/Base64 方式修改图片
|
||
|
||
```bash
|
||
curl -X POST http://192.168.31.5:4000/api/generate \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
|
||
-d "{
|
||
\"prompt\":\"把这张图改成赛博朋克夜景风格，但保留人物脸部特征\",
|
||
\"imageSize\":\"1K\",
|
||
\"aspectRatio\":\"1:1\",
|
||
\"images\":[
|
||
{
|
||
\"mimeType\":\"image/png\",
|
||
\"base64\":\"BASE64_IMAGE_DATA\"
|
||
}
|
||
]
|
||
}"
|
||
```
|
||
|
||
## 常见错误
|
||
|
||
- `Unauthorized. Send Authorization: Bearer YOUR_API_AUTH_TOKEN or x-api-key.`：缺少 API 访问密钥。
|
||
- `Gemini API key is required.`：没有配置 Gemini API Key。
|
||
- `prompt or instruction is required.`：缺少绘制或修改指令。
|
||
- `Unsupported MIME type`：上传文件类型不被模型支持，建议使用 PNG/JPEG/WebP/PDF/TXT/MD。
|
||
|
||
## Agent 调用建议
|
||
|
||
1. NAS 固定 API 地址使用 `http://192.168.31.5:4000`。
|
||
2. 每次调用都必须携带 `Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN` 或 `x-api-key`。
|
||
3. 绘制新图用 `POST /api/generate`。
|
||
4. 修改已有图片用 `POST /api/edit-image`。
|
||
5. 文档分析用 `POST /api/analyze-document`。
|
||
6. 返回图片使用 `images[0].dataUrl` 预览，或解码 `images[0].data` 保存为文件。
|