# 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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978
```

或：

```txt
x-api-key: 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978
```

## 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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978" \
  -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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978" \
  -d "{\"prompt\":\"画一个蓝天白云下的极简风景插画\",\"imageSize\":\"1K\",\"aspectRatio\":\"1:1\"}"
```

PowerShell 保存返回图片：

```powershell
$token='5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978'; $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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978" \
  -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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978" \
  -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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978" \
  -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 5065a4dbb20509600252e6c6a3e9ef075de1d81e0dde19d40800fbbad402d978` 或 `x-api-key`。
3. 绘制新图用 `POST /api/generate`。
4. 修改已有图片用 `POST /api/edit-image`。
5. 文档分析用 `POST /api/analyze-document`。
6. 返回图片使用 `images[0].dataUrl` 预览，或解码 `images[0].data` 保存为文件。