# VectorEngine GPT-image-2 图片生成迁移 2026-05-09

## 背景

GPT-image-2 图片生成此前通过 APIMart OpenAI 兼容入口执行。为统一供应商网关，本次参考 VectorEngine Apifox 文档 `https://vectorengine.apifox.cn/api-448710071`，把仓库内所有 GPT-image-2 生图调用迁移到 VectorEngine，不再使用 APIMart 图片网关。

APIMart 仍只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态理解链路；不要把该文本链路与 GPT-image-2 图片生成配置混用。

## 参考接口

VectorEngine 正式环境基础地址来自 Apifox 项目环境：

```text
https://api.vectorengine.ai
```

GPT-image-2-all 生图接口：

```text
POST /v1/images/generations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {VECTOR_ENGINE_API_KEY}
```

请求体：

```json
{
  "model": "gpt-image-2-all",
  "size": "1024x1024",
  "n": 1,
  "prompt": "生成一只猫"
}
```

参考图场景可按文档字段追加：

```json
{
  "image": ["data:image/png;base64,..."]
}
```

响应体按同步 OpenAI Images 结构读取：

```json
{
  "created": 1776909189,
  "data": [
    {
      "revised_prompt": "",
      "url": "https://pro.filesystem.site/cdn/20260423/example.webp"
    }
  ]
}
```

## 尺寸映射

VectorEngine 文档要求使用像素尺寸，不再使用 APIMart 的比例写法：

| 旧输入 | VectorEngine 请求值 | 用途 |
| --- | --- | --- |
| `1:1`、`1024*1024`、`1024x1024` | `1024x1024` | 拼图、方洞局部贴图、角色主形象 |
| `16:9`、`1280*720`、`1600*900`、`1536x1024` | `1536x1024` | 场景图、封面图、方洞横版背景 |
| `1024x1536` | `1024x1536` | 竖版图 |
| `2048x1152` | `1536x1024` | 开局 CG 故事板首版降为文档明确支持的横版尺寸 |

若调用方传入其它非空尺寸，后端先透传，方便后续跟随 VectorEngine 文档扩展；空值统一回落到 `1024x1024`。

## 后端落点

1. `server-rs/crates/api-server/src/openai_image_generation.rs`
   - 保留当前共享 helper 文件名与函数名，减少 RPG、方洞等调用方改动面。
   - 内部配置改读 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` / `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`。
   - 请求模型固定为 `gpt-image-2-all`，不再写 `official_fallback`。
   - 请求路径改为 `/v1/images/generations`，响应直接解析 `data[].url` / `data[].b64_json`，不再轮询 `/tasks/{task_id}`。
2. `server-rs/crates/api-server/src/puzzle.rs`
   - 拼图默认 `gpt-image-2` 前端值继续兼容，但上游请求模型统一映射到 `gpt-image-2-all`。
   - `nanobanana2` / `gemini-3.1-flash-image-preview` 不再走 APIMart；当前阶段统一回落到 VectorEngine GPT-image-2-all，避免保留旧图片网关。
   - 错误 `details.provider` 改为 `vector-engine`。
   - 入口页上传图若用于首图生成，后端必须在生成成功后同步写入首关 `pictureReference`，保证结果页重新生成默认继续带同一张参考图。
3. `.codex/skills/gpt-image-2-apimart/`
   - 目录名暂不强制迁移，避免本地插件索引漂移；Skill 文案与脚本行为改为 VectorEngine。

## 环境变量

```text
VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
```

说明：

1. GPT-image-2 图片生成不读取 `APIMART_BASE_URL`、`APIMART_API_KEY` 或 `APIMART_IMAGE_REQUEST_TIMEOUT_MS`。
2. `VECTOR_ENGINE_BASE_URL` 仍允许部署环境覆盖，不在代码中绑定私有网关。
3. `VECTOR_ENGINE_API_KEY` 只能进入本地或生产私密环境文件，不提交到 Git。

## 非范围

1. 不迁移创意 Agent 的 APIMart `gpt-5` Responses 链路。
2. 不改变 SpacetimeDB 表结构、migration 或 bindings。
3. 不改前端 UI 文案和模型选择控件展示。
4. 不新增新的图片资产表或图片代理路由。

## 验收

1. 所有 GPT-image-2 生图请求都走 `POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations`。
2. 请求体 `model = gpt-image-2-all`，尺寸为 VectorEngine 支持的像素尺寸。
3. 请求体不再包含 `official_fallback`。
4. 无参考图时使用 `POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations`；有参考图且处于 AI 重绘时改走 `POST {VECTOR_ENGINE_BASE_URL}/v1/images/edits`；入口页关闭 AI 重绘时直接应用上传图，不调用图片生成。
5. 拼图入口页上传图生成首图后，返回的首关 `pictureReference` 保留该 Data URL；结果页重新生成在用户未重新上传参考图时会继续把 `pictureReference` 作为 `referenceImageSrc` 传给后端。
6. 拼图有参考图时，后端 prompt 会显式要求以参考图为第一优先级，保留主体、构图、视角、姿态、配色和光影氛围；入口页会把参考图压到单边 1024 以内，后端拒绝超过 8MB 的参考图字节。
7. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
8. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
9. 运行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`。
10. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。

## 拼图链路排障日志

拼图 `compile_puzzle_draft` 与 `generate_puzzle_images` 进入图片生成时，api-server 会输出分阶段耗时日志。排查“是谁慢”时按同一 `session_id` 串联：

1. `拼图参考图解析完成` / `拼图参考图解析跳过`：确认前端是否传入参考图，以及 Data URL 解析或旧 `/generated-*` OSS 读取耗时；日志只记录 `reference_mime` 与 `reference_bytes`，不记录图片内容。
2. `拼图 VectorEngine 图片生成 HTTP 返回`：VectorEngine `POST /v1/images/generations` 的同步上游耗时，若这一段长，慢点在 VectorEngine 生图接口。
3. `拼图 VectorEngine 图片下载完成`：从 VectorEngine 返回的 `data[].url` 下载正式图耗时。
4. `拼图生成图片已写入 OSS 与资产索引`：正式图上传 OSS、确认资产对象与实体绑定耗时。
5. `拼图图片候选生成完成`：整段候选图生成总耗时。