1

2026-05-09 17:15:23 +08:00
parent 80a4183b45
commit a0ed128bde
43 changed files with 2573 additions and 381 deletions
--- a/docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md
+++ b/docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md
@@ -0,0 +1,128 @@
+# Hyper3D Rodin Gen-2 3D 模型生成接入方案 2026-05-08
+
+## 1. 范围
+
+本方案用于接入 Hyper3D Rodin Gen-2 的文生 3D 模型与图生 3D 模型能力。
+
+本次只做后端安全代理与前端可复用 client，不新增 SpacetimeDB 表，不落正式资产对象，不把 Hyper3D API Key 下发到前端。生成结果仍由调用方在拿到下载链接后决定是否进入 OSS / `asset_object` 的正式资产链。
+
+## 2. 参考接口
+
+参考文档：
+
+- `https://developer.hyper3d.ai/api-specification/rodin-generation-gen2`
+- `https://developer.hyper3d.ai/api-specification/check-status`
+- `https://developer.hyper3d.ai/api-specification/download-results`
+
+上游接口：
+
+```text
+POST https://api.hyper3d.com/api/v2/rodin
+POST https://api.hyper3d.com/api/v2/status
+POST https://api.hyper3d.com/api/v2/download
+```
+
+Rodin Gen-2 提交接口必须使用 `multipart/form-data`。文本生成时提交 `prompt`；图片生成时提交一个或多个 `images` 文件，可选 `prompt` 作为辅助描述。两种模式均固定提交 `tier=Gen-2`。
+
+## 3. 环境变量
+
+```text
+HYPER3D_BASE_URL=https://api.hyper3d.com/api/v2
+HYPER3D_API_KEY=
+HYPER3D_MODEL_REQUEST_TIMEOUT_MS=180000
+```
+
+兼容变量：
+
+```text
+RODIN_BASE_URL
+RODIN_API_KEY
+RODIN_MODEL_REQUEST_TIMEOUT_MS
+```
+
+说明：
+
+1. `HYPER3D_API_KEY` / `RODIN_API_KEY` 只允许写入本地或生产私密环境，不提交到 Git。
+2. 缺少 API Key 时，后端返回 `503 SERVICE_UNAVAILABLE`。
+3. `HYPER3D_BASE_URL` 默认使用公开 API 基础地址；如果团队后续改用代理网关，可通过环境变量覆盖。
+
+## 4. 后端路由
+
+新增 4 个鉴权路由：
+
+| 方法 | 路由 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/assets/hyper3d/text-to-model` | 提交 Rodin Gen-2 文生模型任务 |
+| `POST` | `/api/assets/hyper3d/image-to-model` | 提交 Rodin Gen-2 图生模型任务 |
+| `POST` | `/api/assets/hyper3d/status` | 使用 `subscriptionKey` 查询任务状态 |
+| `POST` | `/api/assets/hyper3d/download` | 使用 `taskUuid` 获取模型下载列表 |
+
+文生模型请求最小体：
+
+```json
+{
+  "prompt": "一只低多边形宝箱，适合 RPG 游戏资产",
+  "geometryFileFormat": "glb",
+  "material": "PBR",
+  "quality": "medium",
+  "meshMode": "Quad",
+  "previewRender": true
+}
+```
+
+图生模型请求最小体：
+
+```json
+{
+  "imageDataUrls": ["data:image/png;base64,..."],
+  "prompt": "保留主体轮廓，生成游戏可用 3D 模型",
+  "conditionMode": "concat",
+  "geometryFileFormat": "glb"
+}
+```
+
+## 5. 约束
+
+1. 图片只接受 `data:image/png|jpeg|webp;base64,...`，最多 5 张。
+2. 单张图片解码后不超过 10MB。
+3. `geometryFileFormat` 限定为 `glb/usdz/fbx/obj/stl`，默认 `glb`。
+4. `material` 限定为 `PBR/Shaded/All`，默认 `PBR`。
+5. `quality` 限定为 `high/medium/low/extra-low`，默认 `medium`。
+6. `meshMode` 限定为 `Quad/Raw`，默认 `Quad`。
+7. `addons` 首版只允许 `HighPack`。
+8. `bboxCondition` 必须为 3 个正数，按上游要求序列化为 JSON 字符串。
+
+## 6. 返回语义
+
+提交任务成功后返回：
+
+```json
+{
+  "ok": true,
+  "provider": "hyper3d-rodin",
+  "mode": "text-to-model",
+  "taskUuid": "task-uuid",
+  "subscriptionKey": "subscription-key",
+  "jobUuids": ["job-uuid"],
+  "message": "Submitted.",
+  "tier": "Gen-2"
+}
+```
+
+状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`。下载接口只返回上游 `list.name` 与 `list.url`，不在后端转存文件。
+
+## 7. 验收
+
+建议执行：
+
+```bash
+npm run check:encoding
+npm run typecheck
+
+cd server-rs
+cargo test -p shared-contracts hyper3d
+cargo test -p api-server hyper3d
+cargo check -p api-server
+```
+
+真实 API smoke 只在本地私密环境设置 `HYPER3D_API_KEY` 后执行。提交生成任务会消耗 Hyper3D Credit，默认验证不自动调用真实生成接口。