# 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`。
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. 参考图字段使用 `image`，不再使用 APIMart 的 `image_urls`。
5. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
6. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
7. 运行 `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`。
8. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。