# 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. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。