# 字字图片插件完整接口文档

> 对应插件版本：`3.1.9`  
> 整理依据：当前插件 `main.py` 与 `ui/index.html`，不是旧版接口说明。  
> 默认中转：`https://api.aicopy.top`，实际请求使用用户在插件中填写的 Base URL。

## 1. 通用配置

| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---:|---|
| `api_key` | string | 空 | 必填，请求头使用 `Authorization: Bearer <API_KEY>` |
| `base_url` | string | `https://api.aicopy.top` | 用户填写的中转地址，插件会去掉末尾 `/` |
| `proxy_url` | string | 空 | 可选，同时用于 HTTP/HTTPS 请求 |
| `model` | string | `image2` | UI 分支内部值 |
| `variant` | string | `(默认)` | 部分分支直接用变体名作为 API `model` |
| `aspect_ratio` | string | `1x1` | 插件 UI 使用 `1x1`、`16x9` 等写法 |
| `resolution` | string | `1k` | `1k`、`2k`、`4k` |
| `generation_timeout` | int | `900` | 生成请求读取超时，单位秒 |
| `download_timeout` | int | `180` | 结果图片下载超时，单位秒 |
| `retry_count` | int | `1` | 网络请求额外重试次数；`1` 表示最多请求 2 次 |

所有接口统一使用：

```http
Authorization: Bearer YOUR_API_KEY
```

JSON 请求还会发送：

```http
Content-Type: application/json
```

Multipart 请求不手动设置 `Content-Type`，由 HTTP 客户端生成 boundary。

插件接口本身由字字动画调用，最重要的宿主输入为：

| 宿主字段 | 类型 | 说明 |
|---|---|---|
| `prompt` | string | 图片描述，原样送入对应上游协议 |
| `reference_images` | dict/list | 参考图容器，详细别名见第 9 节 |
| `output_dir` | string | 生成图片下载后的保存目录 |
| `viewer_index` | int | 用于输出文件名和任务日志定位 |
| `plugin_params` | object | API Key、Base URL、模型、比例、分辨率等插件配置 |
| `progress_callback` | callable | 可选，插件回报生成和保存进度 |

图片生成是同步调用：没有 `task_id`、没有查询端点、没有轮询。上游返回图片后，插件在同一次调用中完成下载/解码并向宿主返回本地路径列表。

## 2. UI 分支与实际模型映射

### 2.1 Gemini 3 (w/ Nano Banana Pro)

- UI `model`：`firefly-nano-banana-pro`
- 接口：流式 Chat，`POST /v1/chat/completions`
- 实际模型规则：`firefly-nano-banana-pro-{resolution}-{aspect_ratio}`
- 示例：选择 `2k + 16x9` 时，实际模型为 `firefly-nano-banana-pro-2k-16x9`
- 比例：`1x1`、`16x9`、`9x16`、`4x3`、`3x4`、`21x9`、`5x4`、`4x5`
- 分辨率：`1k`、`2k`、`4k`
- 参考图：支持，本地图片压缩为 JPEG Data URL 后放入消息内容

### 2.2 Gemini 3.1 (w/ Nano Banana 2)

- UI `model`：`firefly-nano-banana2`
- 接口：流式 Chat，`POST /v1/chat/completions`
- 实际模型规则：`firefly-nano-banana2-{resolution}-{aspect_ratio}`
- 示例：选择 `4k + 9x16` 时，实际模型为 `firefly-nano-banana2-4k-9x16`
- 比例：`1x1`、`16x9`、`9x16`、`4x3`、`3x4`、`21x9`、`3x2`、`5x4`、`4x5`、`2x3`、`8x1`、`1x4`、`1x8`
- 分辨率：`1k`、`2k`、`4k`
- 参考图：支持，处理方式同上

### 2.3 GPT Image2（f系快速生成口）

- UI `model`：`gpt-image-1`
- 接口：流式 Chat，`POST /v1/chat/completions`
- 实际模型规则：`firefly-gpt-image-{resolution}-{aspect_ratio}`
- 示例：`firefly-gpt-image-1k-1x1`
- 比例：`1x1`、`5x4`、`9x16`、`21x9`、`16x9`、`4x3`、`3x2`、`4x5`、`3x4`、`2x3`
- 分辨率：`1k`、`2k`、`4k`
- 参考图：支持

### 2.4 GPT Image2（直连低价口）

- UI `model`：`gpt-image-1-direct`
- 接口：OpenAI 图片接口
- 实际模型规则：`gpt-image-{resolution}-{aspect_ratio}`
- 文生图：`POST /v1/images/generations`
- 图生图：`POST /v1/images/edits`
- 比例：`1x1`、`5x4`、`9x16`、`21x9`、`16x9`、`4x3`、`3x2`、`4x5`、`3x4`、`2x3`
- 分辨率：`1k`、`2k`、`4k`

### 2.5 GPT Image2（备用标准口）

- UI `model`：`image2`
- 实际 API `model`：`gpt-image-2`
- 文生图：`POST /v1/images/generations`
- 图生图：`POST /v1/images/edits`
- 比例和分辨率：同 GPT Image2 直连分支

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

- UI `model`：`image2-adobe`
- 实际 API `model`：`Adobe-gpt-image-2`
- 文生图：`POST /v1/images/generations`
- 图生图：`POST /v1/images/edits`
- 比例和分辨率：同 GPT Image2 直连分支

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

变体名就是提交给 API 的 `model`：

| 变体/实际模型 |
|---|
| `豆姐图片4.0` |
| `豆姐图片4.5` |
| `豆姐图片5.0` |
| `豆姐图片5.0pro` |

- 文生图和图生图都使用 `POST /v1/images/generations`
- 图生图不会走 `/v1/images/edits`
- 参考图转换为 Data URL，放入 JSON 字段 `image`
- 单图时 `image` 是字符串，多图时 `image` 是字符串数组
- 固定附加：`sequential_image_generation="disabled"`、`response_format="url"`、`stream=false`、`watermark=false`
- 比例和分辨率：同 GPT Image2 直连分支

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

变体名就是提交给 API 的 `model`：

| 变体/实际模型 |
|---|
| `香蕉2（标准接口）` |
| `香蕉pro（标准接口）` |
| `香蕉pro-备用（标准接口）` |

- 文生图：`POST /v1/images/generations`，JSON
- 图生图：`POST /v1/images/edits`，multipart/form-data
- 图生图可重复提交多个 `image` 文件字段
- 比例和分辨率：同 GPT Image2 直连分支

### 2.9 协议路由速查

| UI 分支 | 文生图提交 | 有参考图提交 | 请求编码 | 参考图字段 |
|---|---|---|---|---|
| Gemini 3 | `/v1/chat/completions` | 同左 | JSON/SSE | `messages[].content[].image_url.url` Data URL |
| Gemini 3.1 | `/v1/chat/completions` | 同左 | JSON/SSE | `messages[].content[].image_url.url` Data URL |
| GPT Image2 f系快速口 | `/v1/chat/completions` | 同左 | JSON/SSE | `messages[].content[].image_url.url` Data URL |
| GPT Image2 直连低价口 | `/v1/images/generations` | `/v1/images/edits` | JSON / multipart | 重复的 `image` 文件 |
| GPT Image2 备用标准口 | `/v1/images/generations` | `/v1/images/edits` | JSON / multipart | 重复的 `image` 文件 |
| GPT Image2 Adobe高质口 | `/v1/images/generations` | `/v1/images/edits` | JSON / multipart | 重复的 `image` 文件 |
| 豆姐火山稳定出图 | `/v1/images/generations` | 同左 | JSON | `image` Data URL 字符串或数组 |
| 香蕉系列标准接口 | `/v1/images/generations` | `/v1/images/edits` | JSON / multipart | 重复的 `image` 文件 |

## 3. 标准尺寸表

下表用于 GPT Image2、Adobe、豆姐和香蕉标准接口。插件提交的是精确像素字符串：

| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| `1x1` | `1024x1024` | `2048x2048` | `2880x2880` |
| `5x4` | `1280x1024` | `2560x2048` | `3840x3072` |
| `9x16` | `864x1536` | `1728x3072` | `2160x3840` |
| `21x9` | `1792x768` | `3584x1536` | `3840x1646` |
| `16x9` | `1536x864` | `3072x1728` | `3840x2160` |
| `4x3` | `1365x1024` | `2730x2048` | `3840x2880` |
| `3x2` | `1536x1024` | `3072x2048` | `3840x2560` |
| `4x5` | `1024x1280` | `2048x2560` | `3072x3840` |
| `3x4` | `1024x1365` | `2048x2730` | `2880x3840` |
| `2x3` | `1024x1536` | `2048x3072` | `2560x3840` |

## 4. 协议 A：流式 Chat 图片接口

适用分支：Gemini 3、Gemini 3.1、GPT Image2 f系快速生成口。

### 4.1 文生图请求

```bash
curl -N "${BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-gpt-image-1k-1x1",
    "messages": [{
      "role": "user",
      "content": [{"type": "text", "text": "一只赛博朋克风格的小猫"}]
    }],
    "stream": true
  }'
```

### 4.2 带参考图请求

插件会将每张本地图片：

1. 转为 RGB；
2. 最长边超过 1024 时等比缩小；
3. 编码为质量 85 的 JPEG；
4. 放入 `data:image/jpeg;base64,...`。

```json
{
  "model": "firefly-nano-banana-pro-2k-16x9",
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "image_url",
        "image_url": {"url": "data:image/jpeg;base64,..."}
      },
      {"type": "text", "text": "保持主体，改成电影海报风格"}
    ]
  }],
  "stream": true
}
```

### 4.3 流式返回

插件读取 SSE：

```text
data: {"choices":[{"delta":{"content":"![image](https://example.com/result.png)"}}]}
data: [DONE]
```

结果 URL 可为：

- Markdown 图片：`![...](https://...)`
- 任意 `http://` 或 `https://` URL
- 相对 API 路径：`/v1/...`，插件会拼接 Base URL

如果流式返回中没有提取到图片 URL，插件会用同一请求体把 `stream` 改为 `false` 再请求一次，并读取：

```json
{
  "choices": [{
    "message": {
      "content": "https://example.com/result.png"
    }
  }]
}
```

## 5. 协议 B：OpenAI 图片接口

适用分支：GPT Image2 直连、GPT Image2 备用、Adobe高质口。

### 5.1 文生图

```bash
curl "${BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只赛博朋克风格的小猫",
    "n": 1,
    "aspect_ratio": "16x9",
    "resolution": "1k",
    "size": "1536x864"
  }'
```

直连分支示例模型为 `gpt-image-1k-16x9`；备用分支为 `gpt-image-2`；Adobe 分支为 `Adobe-gpt-image-2`。

### 5.2 图生图

```bash
curl "${BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "model=gpt-image-2" \
  -F "prompt=保持主体，改成电影海报风格" \
  -F "n=1" \
  -F "aspect_ratio=16x9" \
  -F "resolution=1k" \
  -F "size=1536x864" \
  -F "image=@./input-1.png" \
  -F "image=@./input-2.png"
```

插件对每张参考图重复使用字段名 `image`。

## 6. 协议 C：豆姐火山接口

### 6.1 文生图

```bash
curl "${BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "豆姐图片5.0",
    "prompt": "生成一张电影海报",
    "sequential_image_generation": "disabled",
    "response_format": "url",
    "size": "1536x864",
    "stream": false,
    "watermark": false
  }'
```

### 6.2 图生图

```json
{
  "model": "豆姐图片5.0",
  "prompt": "保持人物一致，改成电影海报",
  "sequential_image_generation": "disabled",
  "response_format": "url",
  "size": "1536x864",
  "stream": false,
  "watermark": false,
  "image": [
    "data:image/png;base64,...",
    "data:image/jpeg;base64,..."
  ]
}
```

只有一张参考图时，`image` 为字符串，不是数组。

## 7. 协议 D：香蕉标准接口

### 7.1 文生图

```bash
curl "${BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "香蕉2（标准接口）",
    "prompt": "一只赛博朋克风格的小猫",
    "size": "1536x864",
    "n": 1
  }'
```

此协议不会额外提交 `aspect_ratio`、`resolution`、`watermark` 或 `stream`。

### 7.2 图生图

```bash
curl "${BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "model=香蕉pro（标准接口）" \
  -F "prompt=保持人物一致，改成电影海报风格" \
  -F "image=@./input-1.png" \
  -F "image=@./input-2.jpg"
```

图生图请求只提交 `model`、`prompt` 和重复的 `image` 文件，不提交 `size` 与 `n`。

## 8. 图片返回格式

所有 `/v1/images/*` 分支要求 HTTP `200`，并从 `data` 数组读取结果。

### 8.1 URL 返回

```json
{
  "data": [
    {"url": "https://example.com/result.png"}
  ]
}
```

### 8.2 Base64 返回

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

兼容规则：

- `b64_json` 优先于 `url`；
- 相对 URL（以 `/` 开头）会拼接 Base URL；
- `data` 为空时报 `No image data in response`；
- 有 `data` 但没有可保存的 `url/b64_json` 时，报 `No image was saved`。

图片接口是同步接口，没有任务 ID，也没有轮询查询步骤。生成成功后插件立即下载并保存本地文件。

上游图片请求必须返回 HTTP `200`；`201/202` 不会被视为成功。插件最终向字字动画返回：

```python
["F:/.../generated_0.png", "F:/.../generated_1.png"]
```

通常 `n=1` 只返回一个路径；如果上游 `data` 数组含多张图，插件会逐张保存并返回全部本地路径。

## 9. 参考图识别规则

插件兼容以下常见容器键：

```text
参考图片MAP / 参考图MAP / 参考图片 / 参考图
reference_images / reference_image
ref_images / ref_image / image_references
images / image_paths / uploaded_images
```

还兼容宿主传入的 `reference_items`、`media_items`、`input_images`、`first_frame_path`、`end_frame_path` 等字段。

对于 OpenAI 图片接口和香蕉标准接口：

- 检测到“有参考图”的信号但无法解析出有效本地图片时，插件会在本地停止；
- 不会静默降级成文生图；
- HTTP/HTTPS 图片 URL 不会直接作为 `/v1/images/edits` 文件，当前实现要求可读取的本地文件。

## 10. 错误格式与处理

### 10.1 标准结构化错误

```json
{
  "error": {
    "message": "invalid API key",
    "type": "invalid_request_error",
    "code": 401
  }
}
```

也兼容：

```json
{"error":"错误内容"}
```

```json
{"message":"错误内容"}
```

插件优先提取 `error.message`，其次 `error`，再其次顶层 `message`。

### 10.2 HTML 网关错误

- HTTP 504 且响应为 Gateway Timeout 时，插件提示：请求可能已到达上游，不建议立即重复提交；
- 其他 HTML 错误页会提取 `<title>`，显示为“中转返回错误页”。

### 10.3 流式 Chat 错误

兼容普通 JSON 错误行：

```json
{"error":{"message":"generation failed"}}
```

也会检查 SSE `delta.reasoning_content` 中是否出现错误描述。

### 10.4 本地常见错误

| 错误 | 含义 |
|---|---|
| `API Key 未设置` | 插件没有读取到密钥 |
| `检测到参考图输入，但无法读取有效的本地图片` | 宿主传了参考项，但路径失效或无法解析 |
| `No image data in response` | HTTP 成功，但响应没有有效 `data` |
| `Could not extract image URL from response` | Chat 流和非流回退都未返回可识别 URL |
| `Failed to save image` | 结果存在，但下载或本地保存失败 |

## 11. 完整调用流程

```text
读取插件配置
  -> 校验分支、比例和分辨率
  -> 将 UI 分支/变体映射为实际 model
  -> 收集并校验参考图
  -> 选择 Chat / Images / 豆姐 / 香蕉协议
  -> 提交同步生成请求
  -> 解析 URL 或 b64_json
  -> 下载/解码结果
  -> 保存到字字动画输出目录
  -> 写入本地任务日志
```