1

docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md

@@ -0,0 +1,116 @@
+# 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`。