Rodin Gen-2

根据图片和/或文本提示生成网格与纹理。

Authorization

bearer

AuthorizationBearer <token>

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

images*array<string>

用于生成的图片，最多 5 张。请求体中的上传顺序会被保留。Image-to-3D 至少需要一张图片；Text-to-3D 不提交此字段。

prompt?string

用于指导生成的文本提示。Text-to-3D 必填；Image-to-3D 可选。提示词会先生成为图片，因此纯文本请求也可能返回 IMAGE_CONTENT_VIOLATION。

tier*string

必填。请显式设置该字段为 `Gen-2`。若省略，接口会回退到 `Regular` 并生成 Gen-1/1.5 资产。

mesh_mode?string

可选，控制生成模型的拓扑结构。`Raw` 表示三角面拓扑，`Quad` 表示四边面拓扑。默认值取决于所选的 `tier`：Gen-2.5 tiers 默认使用 `Raw`，其他 tiers 默认使用 `Quad`。

geometry_file_format?string

可选，控制生成模型的文件格式。

material?string

可选，材质类型。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。

quality?string

可选。Gen-2 的预设目标面数，默认为 `medium`。映射取决于 `mesh_mode`： - `Quad`：`high` 50000、`medium` 18000、`low` 8000、`extra-low` 4000； - `Raw`：`high` 500000、`medium` 150000、`low` 20000、`extra-low` 2000。

quality_override?number

可选。Gen-2 的自定义目标面数，取值范围为 500 到 1000000，提交后优先于 `quality`。`Quad` 模式另有 200000 的上限；`Raw` 模式最高支持 1000000。

seed?integer

可选，随机种子。

bbox_condition?array<>

可选。控制生成模型的最大尺寸。请严格按宽度（X 轴）、高度（Y 轴）、长度（Z 轴）的 `(x, y, z)` 顺序提供三个整数。参阅 [BBOX Control](/zh/api-specification/bbox-control)。

addons?array<>

可选付费附加项。将 pack 纹理从 2K 升级到 4K。对于 Gen-2，HighPack 不会改变几何体，也不会额外生成高模。

TAPose?boolean

可选，对于类人型模型，使用适合动画的 T-pose 或 A-pose 参考姿态生成结果。

use_original_alpha?boolean

可选，是否使用原始 alpha 通道。默认值为 `false`。当原图无有效的 alpha 通道时，此参数无效。

preview_render?boolean

可选，是否生成预览。默认值为 false。

hd_texture?boolean

可选。启用额外的纹理超分辨率和增强处理步骤。这可以提升细节清晰度，但也可能引入伪影。该功能不会决定最终的 2K 或 4K 打包分辨率；如需 4K 输出，请使用 HighPack 附加组件。

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/rodin" \  -F tier="Gen-2"

{  "error": "NO_SUCH_TASK",  "message": "Submitted.",  "uuid": "123e4567-e89b-12d3-a456-426614174000",  "submit_time": "2019-08-24T14:15:22Z",  "jobs": {    "uuids": [      "52faea01-729e-4195-85e8-6050a65315e3"    ],    "subscription_key": "string"  },  "consumed": 0.5,  "prompt": "string"}

输入

设置 tier=Gen-2。Image-to-3D 提交一到五个 images，并可选提交 prompt；Text-to-3D 提交 prompt，并省略 images。

tier 为必传参数

请始终显式传入 tier=Gen-2。如果省略 tier，endpoint 会回退到 Regular 并生成 Gen-1/1.5 asset。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rodin' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'images=@./input.png' \
  --form 'tier=Gen-2' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

HighPack 会把 pack 纹理从 2K 升级到 4K。对于 Gen-2，它不会改变几何体，也不会额外生成高模。

计费

项目	扣费
Gen-2 基础生成	`0.5 credits`
`addons` 包含 `HighPack`	`+1.0 credits`

各项费用累加计算。基础生成仅需 0.5 credits；除上表列出的参数外，其他参数均不会产生额外费用。

响应与生命周期

{
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
    "uuids": ["223e4567-e89b-12d3-a456-426614174000"],
    "subscription_key": "subscription-key-from-generation-response"
  },
  "consumed": 0.5
}

使用 jobs.subscription_key 查询状态，使用顶层 uuid 下载结果。HTTP 201 仅表示 endpoint 已处理请求；只有在 error 缺失或为空且顶层 uuid 非空时，任务才算已受理。400 表示字段或文件无效，401 表示鉴权无效，429 表示触发限流。