# 小裴图片插件接口文档

版本：`3.1.29`  
整理依据：当前运行版 `main.py` 与 `ui/index.html` 的实际请求逻辑  
默认中转：`https://api.aicopy.top`

> 本文档记录插件实际发出的请求。图片参考素材会使用当前电脑上的
> 原图路径处理，不使用画布的 `thumbnails_500` 预览图。流式
> Chat/对话接口分支已按要求排除。

## 一、接口总览

| UI 分支 | `api_type` | 实际提交接口 | 参考图方式 | 实际模型名规则 |
|---|---|---|---|---|
| GPT Image2(直连低价口） | `openai_images` | `POST /v1/images/generations` 或 `POST /v1/images/edits` | 无图 JSON；有图 multipart | `gpt-image-{resolution}-{aspect_ratio}` |
| GPT Image2(备用标准口） | `openai_images` | 同上 | 同上 | `gpt-image-2` |
| GPT Image2一专业作图（4k原生口） | `openai_images` | 同上 | 同上 | `gpt-image-2-原生4k` |
| GPT Image2(福利特价口) | `openai_images` | 同上 | 同上 | `gpt-image-2特价1k/2k/4k` |
| GPT Image2 (Adobe高质口) | `openai_images` | 同上 | 同上 | `Adobe-gpt-image-2` |
| 【豆姐】火山稳定出图 | `openai_images` | `POST /v1/images/generations` | 先上传 URL，再传 `image` | 变体名原样发送 |
| 香蕉系列（标准接口） | `openai_images` | `POST /v1/images/generations` | 先上传 URL，再传 `image` | 变体名原样发送 |

所有 JSON 请求使用：

```http
Authorization: Bearer <中转秘钥>
Content-Type: application/json
```

有参考图的 GPT Image2 类请求使用 `multipart/form-data`，由 HTTP 客户端
自动生成 boundary，不要手写 JSON 的 Content-Type。

## 二、通用参数

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `model` | string | `image2` | UI 内部分支键，不一定是实际发送模型名 |
| `variant` | string | `(默认)` | 豆姐、香蕉用于选择实际模型 |
| `aspect_ratio` | string | `1x1` | 实际格式为 `1x1`、`16x9`，不是冒号格式 |
| `resolution` | string | `1k` | `1k`、`2k`、`4k` |
| `base_url` | string | `https://api.aicopy.top` | 中转根地址，自动去掉结尾斜杠 |
| `api_key` | string | 空 | 中转秘钥 |
| `proxy_url` | string | 空 | 留空自动检测当前运行电脑的代理 |
| `generation_timeout` | integer | `900` | 生成请求超时秒数 |
| `download_timeout` | integer | `180` | 图片下载超时秒数 |
| `retry_count` | integer | `1` | 请求和下载重试次数，最小为 0 |

当前比例选项：

```text
1x1, 5x4, 9x16, 21x9, 16x9, 4x3, 3x2, 4x5, 3x4, 2x3
```

## 三、GPT Image2 尺寸表

GPT Image2 类模型实际发送 `size`。每个分辨率和比例组合独立映射：

| 比例 | 1k | 2k | 4k |
|---|---:|---:|---:|
| `1x1` | `1024x1024` | `2048x2048` | `2880x2880` |
| `16x9` | `1536x864` | `2048x1152` | `3840x2160` |
| `9x16` | `864x1536` | `1152x2048` | `2160x3840` |
| `4x3` | `1365x1024` | `2048x1536` | `3840x2880` |
| `3x4` | `1024x1365` | `1536x2048` | `2880x3840` |
| `3x2` | `1536x1024` | `2048x1365` | `3840x2560` |
| `2x3` | `1024x1536` | `1365x2048` | `2560x3840` |
| `4x5` | `1024x1280` | `1638x2048` | `3072x3840` |
| `5x4` | `1280x1024` | `2048x1638` | `3840x3072` |
| `21x9` | `1792x768` | `2048x878` | `3840x1646` |

## 四、分支与模型

### 4.1 GPT Image2(直连低价口）

- UI 分支键：`gpt-image-1-direct`
- 变体：`(默认)`
- 实际模型：`gpt-image-{resolution}-{aspect_ratio}`
- 分辨率：`1k`、`2k`、`4k`
- 无参考图走 `/v1/images/generations`，有参考图走 `/v1/images/edits`

### 4.2 GPT Image2(备用标准口）

- UI 分支键：`image2`
- 变体：`(默认)`
- 实际模型：`gpt-image-2`
- 分辨率、比例和请求结构同 4.1。

### 4.3 GPT Image2一专业作图（4k原生口）

- UI 分支键：`image2-native-4k`
- 变体：`(默认)`
- 实际模型：`gpt-image-2-原生4k`
- 只开放 `4k`，`size` 使用尺寸表的 4k 列。

### 4.4 GPT Image2(福利特价口)

- UI 分支键：`image2-benefit`
- 变体：`(默认)`

| `resolution` | 实际 `model` |
|---|---|
| `1k` | `gpt-image-2特价1k` |
| `2k` | `gpt-image-2特价2k` |
| `4k` | `gpt-image-2特价4k` |

### 4.5 GPT Image2 (Adobe高质口)

- UI 分支键：`image2-adobe`
- 变体：`(默认)`
- 实际模型：`Adobe-gpt-image-2`
- 分辨率、比例和请求结构同 4.1。

### 4.6 【豆姐】火山稳定出图

- UI 分支键：`doujie-volcano-stable`
- 变体和实际模型名：
  `豆姐图片4.0`、`豆姐图片4.5`、`豆姐图片5.0`、
  `豆姐图片5.0pro`
- 分辨率：`1k`、`2k`、`4k`
- 参考图先上传为公网 URL，再请求 `/v1/images/generations`
- 当前不发送 `size`，只发送 `aspect_ratio` 和 `resolution`

### 4.7 香蕉系列（标准接口）

- UI 分支键：`banana-standard`
- 变体和实际模型名：
  `香蕉2（标准接口）`、`香蕉pro（标准接口）`、
  `香蕉pro-备用（标准接口）`
- 分辨率：`1k`、`2k`、`4k`
- 参考图先上传为公网 URL，再请求 `/v1/images/generations`
- 当前不发送 `size`；字段模板与豆姐分支相同

## 五、GPT Image2 类文生图

适用：直连低价、备用标准、原生 4k、福利特价、Adobe 高质。

### 5.1 完整 JSON

```json
{
  "model": "gpt-image-2",
  "prompt": "一只猫坐在窗边，电影感光影",
  "n": 1,
  "aspect_ratio": "16x9",
  "resolution": "2k",
  "size": "2048x1152"
}
```

### 5.2 完整 cURL

```bash
curl -X POST "https://api.aicopy.top/v1/images/generations" \\
  -H "Authorization: Bearer <中转秘钥>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只猫坐在窗边，电影感光影",
    "n": 1,
    "aspect_ratio": "16x9",
    "resolution": "2k",
    "size": "2048x1152"
  }'
```

### 5.3 其他模型请求示例

```json
{
  "model": "gpt-image-2-原生4k",
  "prompt": "电影级产品静物，黑色背景，边缘轮廓光",
  "n": 1,
  "aspect_ratio": "1x1",
  "resolution": "4k",
  "size": "2880x2880"
}
```

```json
{
  "model": "gpt-image-2特价2k",
  "prompt": "现代建筑外立面，清晰材质，午后阳光",
  "n": 1,
  "aspect_ratio": "16x9",
  "resolution": "2k",
  "size": "2048x1152"
}
```

## 六、GPT Image2 类参考图

### 6.1 实际接口和字段

```http
POST https://api.aicopy.top/v1/images/edits
Authorization: Bearer <中转秘钥>
Content-Type: multipart/form-data
```

| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
| `model` | string | `gpt-image-2` | 实际模型名 |
| `prompt` | string | `保持人物外观一致` | 编辑提示词 |
| `n` | string | `1` | 生成数量 |
| `aspect_ratio` | string | `9x16` | 目标比例 |
| `resolution` | string | `1k` | 目标分辨率 |
| `size` | string | `864x1536` | 按尺寸表计算 |
| `image` | file | `reference-1.jpg` | 每张图一个同名字段 |

### 6.2 cURL

```bash
curl -X POST "https://api.aicopy.top/v1/images/edits" \\
  -H "Authorization: Bearer <中转秘钥>" \\
  -F "model=gpt-image-2" \\
  -F "prompt=保持人物外观一致，生成雨夜街头肖像" \\
  -F "n=1" \\
  -F "aspect_ratio=9x16" \\
  -F "resolution=1k" \\
  -F "size=864x1536" \\
  -F "image=@reference-1.jpg" \\
  -F "image=@reference-2.jpg"
```

插件上传前会把原图最长边压到不超过 `1024px`，JPEG 质量约为 `85`。
画布预览路径会尝试映射到项目原图；无法定位原图时停止提交。

## 七、豆姐与香蕉请求

### 7.1 参考图上传

```http
POST <base_url>/v1/uploads
POST <base_url>/v1/upload
```

上传为 multipart，字段为 `image`：

```bash
curl -X POST "https://api.aicopy.top/v1/uploads" \\
  -H "Authorization: Bearer <中转秘钥>" \\
  -F "image=@reference.jpg"
```

插件从以下位置提取公网 URL：

```text
image_url / file_url / url
data.image_url / data.file_url / data.url
image_urls[0] / file_urls[0] / urls[0]
data.image_urls[0] / data.file_urls[0] / data.urls[0]
```

当前中转地址上传失败时，还会尝试 `https://api.aione.help` 的同名路径。

### 7.2 无参考图

```json
{
  "model": "香蕉2（标准接口）",
  "prompt": "一只猫坐在窗边，电影感光影",
  "sequential_image_generation": "disabled",
  "response_format": "url",
  "aspect_ratio": "16x9",
  "resolution": "2k",
  "stream": false,
  "watermark": false
}
```

豆姐示例只替换模型：

```json
{
  "model": "豆姐图片4.5",
  "prompt": "商业产品摄影，干净背景，柔和轮廓光",
  "sequential_image_generation": "disabled",
  "response_format": "url",
  "aspect_ratio": "1x1",
  "resolution": "4k",
  "stream": false,
  "watermark": false
}
```

### 7.3 单张参考图

```json
{
  "model": "香蕉pro（标准接口）",
  "prompt": "参考图片中的产品外观，生成电商主图",
  "sequential_image_generation": "disabled",
  "response_format": "url",
  "aspect_ratio": "4x5",
  "resolution": "2k",
  "stream": false,
  "watermark": false,
  "image": "https://cdn.example.com/reference-1.jpg"
}
```

### 7.4 多张参考图

```json
{
  "model": "豆姐图片5.0",
  "prompt": "综合参考所有图片，保持主体外观一致，生成商业广告画面",
  "sequential_image_generation": "disabled",
  "response_format": "url",
  "aspect_ratio": "16x9",
  "resolution": "2k",
  "stream": false,
  "watermark": false,
  "image": [
    "https://cdn.example.com/reference-1.jpg",
    "https://cdn.example.com/reference-2.jpg"
  ]
}
```

注意：多图字段是 `image` 数组，不是 `images`；这套请求没有
`n` 和 `size`。

## 八、返回与错误处理

成功响应：

```json
{
  "data": [
    {
      "url": "https://cdn.example.com/generated/image-001.png"
    }
  ]
}
```

也兼容：

```json
{
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

插件按以下顺序处理：

1. 读取 `data` 数组。
2. 优先下载 `url`；相对 URL 自动拼接当前 `base_url`。
3. 没有 URL 时读取 `b64_json` 并保存。
4. 下载/保存成功后写入当前任务日志。

常见失败包括：未配置 Key、参考图不可读、预览图找不到原图、上传没有
返回公网 URL、HTTP 非 200、`data` 为空或结果没有 `url/b64_json`。

## 九、接口边界

流式 Chat/对话接口分支不属于本文档的图片生成接口，未在本文档中展开；
请勿将其请求字段与本文档的 `/v1/images/generations`、`/v1/images/edits`
字段混用。