拼图图片模型路由接入 2026-05-01

2026-05-09 更新：GPT-image-2 图片生成已从 APIMart 迁移到 VectorEngine。本文保留前端模型选择和拼图扣费/持久化历史设计，图片上游接口、环境变量和请求体以 VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md 为准。

背景

拼图创作已收口为填表式流程，首图生成和结果页关卡重新生成都由 server-rs/crates/api-server/src/puzzle.rs 执行外部图片 I/O，再把正式图写入 OSS 与 SpacetimeDB。新的模型选择只影响图片生成上游，不改变 SpacetimeDB 表结构、拼图草稿结构或前端运行时规则。

历史版本曾参考 APIMart 文档；当前 GPT-image-2 图片生成参考 VectorEngine Apifox 文档：

https://vectorengine.apifox.cn/api-448710071

当前图片生成入口：POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations，头部使用 Authorization: Bearer {VECTOR_ENGINE_API_KEY}。请求体至少包含 model = gpt-image-2-all、prompt、n、size，参考图使用 image 数组。返回体按同步 OpenAI images 结构读取 data[].url 或 data[].b64_json，不再轮询 APIMart tasks/{task_id}。

模型选项

拼图图片生成支持两个选项：

前端显示	请求值	上游
`gpt-image-2`	`gpt-image-2`	VectorEngine `/v1/images/generations`，上游模型 `gpt-image-2-all`
`nanobanana2`	`gemini-3.1-flash-image-preview`	历史兼容选项，后端回落到 VectorEngine `gpt-image-2-all`

默认值为 gpt-image-2。前端只负责展示和传递所选模型，不能把模型路由逻辑、上游请求体拼装或 API Key 暴露到浏览器。历史草稿或旧请求中的空值、original、未知值统一按 gpt-image-2 处理，不再把拼图生图路由回 DashScope 原模型。

前端交互

拼图创作表单的“画面描述”输入框左下角显示当前调用模型。
拼图结果页关卡详情的“画面描述”输入框左下角同样显示当前调用模型。
点击模型标识弹出轻量选择菜单，只支持 gpt-image-2、nanobanana2 两项。
菜单只是模型选择控件，不写入说明性规则文案。
参考图入口继续在画面描述输入框右下角，模型选择在左下角，两者不得遮挡文本。
表单创建 session、自动保存表单草稿、首图生成失败重试时都要保留当前模型选择。
结果页关卡重新生成时将当前模型随 generate_puzzle_images action 传给后端。
“生成草稿”和关卡详情“生成画面 / 重新生成画面”按钮文本右侧展示 消耗2光点。
关卡详情点击“生成画面 / 重新生成画面”后先弹出确认消耗光点弹窗，确认后开始请求；按钮区域切换为 30 秒倒计时进度条，并展示预计剩余生成完成时间。

后端路由

CreatePuzzleAgentSessionRequest 与 ExecutePuzzleAgentActionRequest 增加可选 imageModel 字段；该字段不进入 SpacetimeDB reducer 输入结构。
compile_puzzle_draft_with_initial_cover 与 generate_puzzle_image_candidates 增加图片模型参数。
imageModel 归一化规则：
- 空值、original 或未知值统一回落为 gpt-image-2；
- gpt-image-2 走 VectorEngine；
- gemini-3.1-flash-image-preview 不再走 APIMart，前端显示名仍为 nanobanana2，后端统一回落到 VectorEngine gpt-image-2-all。
VectorEngine 文生图和图生图共用 POST /v1/images/generations。有参考图时，后端将参考图 Data URL 作为 image 数组传入；若上游不接受该字段，错误按上游失败返回，不在前端降级伪造结果。
VectorEngine 拼图尺寸使用 1024x1024，请求体不携带 official_fallback。
VectorEngine 生成成功后仍下载远程图片，沿用现有 OSS 私有对象、asset_object 和 asset_entity_binding 写入流程。若图片已成功上传 OSS，但 SpacetimeDB 短暂返回 503 Service Unavailable，资产索引写入允许降级跳过，并返回本次生成图片；日志必须记录 拼图图片资产索引写入因 SpacetimeDB 连接不可用而降级跳过。
save_puzzle_generated_images 写回草稿时若遇到 SpacetimeDB 连接级 503 或断线，API 层基于本次生成结果合成 session 快照返回给前端，避免 VectorEngine 已成功出图却被后置持久化误报成服务不可用。余额不足、参数错误、上游生图失败仍按原错误返回，不做伪成功。
结果页 generate_puzzle_images 会携带当前作品信息和 levelsJson。当 SpacetimeDB 在读取 session 阶段就返回连接级 503 或断线时，后端必须先用这份结果页快照构造最小内存 session，再继续调用 VectorEngine；外部图片已经生成后仍按第 6、7 条处理持久化降级。余额不足、参数错误、缺少草稿快照、关卡不存在等业务错误不走此降级。
VectorEngine 错误统一映射为 502 UPSTREAM_ERROR，details.provider = "vector-engine"，保留上游状态码、业务 message 和截断后的 raw excerpt。
拼图首图生成 compile_puzzle_draft 与关卡图片生成 generate_puzzle_images 每次预扣 2 光点；余额不足仍返回 409 CONFLICT，SpacetimeDB 连接级 503 仍按既有降级策略处理。

关卡名多模态生成

第一关和结果页关卡重新生图的最终关卡名统一由 APIMart Chat Completions gpt-4o-mini 生成。
输入必须同时包含生成完成后的正式图片和当前关卡 pictureDescription；图片由 api-server 从生成结果字节压缩为最多 768 边长的 PNG Data URL 后，以 OpenAI 兼容 messages[].content[] 的 image_url 形式传入。
文本模型仍只输出 {"levelName":"..."}，并继续复用现有 2 到 8 个中文字符、禁用“画面 / 拼图 / 作品”等泛词的解析与归一化规则。
gpt-4o-mini 调用失败、返回非法或 APIMart 文本配置缺失时，不阻断图片生成；后端保留图片生成前的文本关卡名或确定性兜底名。
关卡名与候选图在同一次 save_puzzle_generated_images 中写回 levels_json 和正式候选图，避免图片与关卡名不同步。

环境变量

新增服务端环境变量：

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

VECTOR_ENGINE_API_KEY 只能存在于本地或部署环境，不写入 Git 跟踪文件。若缺少 key，后端返回服务不可用错误，前端展示现有错误面板。

验收

创作表单和关卡详情的画面描述框左下角能切换 gpt-image-2、nanobanana2，默认显示 gpt-image-2。
点击“生成草稿”时，后端首图生成使用当前表单选择的模型。
点击“生成画面 / 重新生成画面”时，后端当前关卡图片生成使用关卡详情选择的模型。
历史 original 或空模型值不会再触发 DashScope，统一按 gpt-image-2 请求 VectorEngine。
选择图片模型时，请求 POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations，使用 Authorization: Bearer {VECTOR_ENGINE_API_KEY}，上游 model = gpt-image-2-all，不携带 official_fallback，size = 1024x1024。
首图和结果页关卡重新生图成功后，Network 中应先完成 VectorEngine 图片生成，再调用 APIMart POST {APIMART_BASE_URL}/chat/completions，请求模型为 gpt-4o-mini，消息同时包含画面描述文本和正式图 image_url Data URL。
“生成草稿”和关卡详情生图按钮展示 消耗2光点；关卡详情确认后展示 30 秒预计剩余进度条。
不改 SpacetimeDB 表结构，因此无需更新 migration.rs 或重新生成 bindings。
后端改动后运行对应 Rust 测试，并按项目约束用 npm run api-server 重启验证。

7.8 KiB Raw Blame History Unescape Escape