1

docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md

@@ -13,6 +13,8 @@
 - `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`
+- `https://developer.hyper3d.ai/api-specification/check-status_reset_v`
+- `https://developer.hyper3d.ai/api-specification/download-results_reset_v`
 
 上游接口：
 
@@ -24,6 +26,11 @@ POST https://api.hyper3d.com/api/v2/download
 
 Rodin Gen-2 提交接口必须使用 `multipart/form-data`。文本生成时提交 `prompt`；图片生成时提交一个或多个 `images` 文件，可选 `prompt` 作为辅助描述。两种模式均固定提交 `tier=Gen-2`。
 
+官方 `*_reset_v` 文档对状态和下载有两个关键约束：
+
+1. 生成接口返回的顶层 `uuid` 是后续下载接口的 `task_uuid`，不要使用 `jobs.uuids` 中的子任务 uuid 作为下载参数。
+2. 状态接口使用 `subscription_key` 查询，并返回 `jobs[]`；只有所有 job 的 `status` 都为 `Done` 才能进入下载，任一 job `Failed` 都应视为任务失败。
+
 ## 3. 环境变量
 
 ```text
@@ -111,7 +118,7 @@ RODIN_MODEL_REQUEST_TIMEOUT_MS
 }
 ```
 
-状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`。下载接口只返回上游 `list.name` 与 `list.url`，不在后端转存文件。
+状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`，整体状态必须以 `jobs[]` 聚合结果为准。下载接口只返回上游 `list.name` 与 `list.url`，不在 Hyper3D 代理路由中转存文件；具体玩法若需要持久化模型，应在玩法编排层等待 `Done` 后再下载并转存。
 
 ## 7. 验收