add nas agent api guide

2026-05-09 19:16:39 +08:00
parent 84ebdbd793
commit 415c5b6474
2 changed files with 143 additions and 1 deletions
--- a/API图片绘制及修改-Agent-NAS.md
+++ b/API图片绘制及修改-Agent-NAS.md
@@ -0,0 +1,139 @@
+# 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` 保存为文件。
--- a/README.md
+++ b/README.md
@@ -101,7 +101,10 @@ curl -X POST http://localhost:3002/api/analyze-document \

 API auth is required by default. For local-only development, you can set `API_AUTH_DISABLED=true`, but do not use that on a LAN or server.

-For Agent-facing image generation and editing instructions, see `API图片绘制及修改-Agent.md`.
+For Agent-facing image generation and editing instructions, see:
+
+- `API图片绘制及修改-Agent.md`: generic/local API usage.
+- `API图片绘制及修改-Agent-NAS.md`: NAS usage with `192.168.31.5:4000`.

 ## Docker Compose Deploy