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 项目环境：

https://api.vectorengine.ai

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

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

请求体：

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

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

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

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

{
  "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`、`1280720`、`1600900`、`1536x1024`	`1536x1024`	场景图、封面图、方洞横版背景
`1024x1536`	`1024x1536`	竖版图
`2048x1152`	`1536x1024`	开局 CG 故事板首版降为文档明确支持的横版尺寸

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

后端落点

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}。
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，保证结果页重新生成默认继续带同一张参考图。
.codex/skills/gpt-image-2-apimart/
- 目录名暂不强制迁移，避免本地插件索引漂移；Skill 文案与脚本行为改为 VectorEngine。

环境变量

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

说明：

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

非范围

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

验收

所有 GPT-image-2 生图请求都走 POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations。
请求体 model = gpt-image-2-all，尺寸为 VectorEngine 支持的像素尺寸。
请求体不再包含 official_fallback。
参考图字段使用 image，不再使用 APIMart 的 image_urls。
拼图入口页上传图生成首图后，返回的首关 pictureReference 保留该 Data URL；结果页重新生成在用户未重新上传参考图时会继续把 pictureReference 作为 referenceImageSrc 传给后端。
缺少 VECTOR_ENGINE_BASE_URL 或 VECTOR_ENGINE_API_KEY 时返回 503 SERVICE_UNAVAILABLE，details.provider = "vector-engine"。
上游错误映射为 502 UPSTREAM_ERROR，保留 upstreamStatus、业务 message 和截断后的 raw excerpt。
运行 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。
后端改动后使用 npm run api-server 重启，并确认 /healthz。

拼图链路排障日志

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

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

6.0 KiB Raw Blame History Unescape Escape