Rodin Gen-2.5

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

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.5 档位。若省略，接口会回退到 `Regular` 并生成 Gen-1/1.5 资产。更多信息请参阅 [Tier](/zh/api-specification/rodin-gen2-5#tier)。此参数可能影响计费，请参阅 [计费](/zh/api-specification/rodin-gen2-5#计费)。

mesh_mode?string

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

geometry_file_format?string

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

texture_mode?string

可选。生成模型的纹理模式。较高的模式通常会产生更丰富、更高分辨率的纹理细节，但耗时更长且可能影响计费。请参阅 [计费](/zh/api-specification/rodin-gen2-5#计费)。 - `legacy`：使用旧版纹理管线。 - `extreme-high`：可生成最高 12K 纹理。请参阅 [如何生成 12K 纹理](/zh/api-specification/rodin-gen2-5#如何生成-12k-纹理)。默认值取决于所选的 `tier`，请参阅 [纹理模式](/zh/api-specification/rodin-gen2-5#texture-mode)。

material?string

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

quality?string

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

quality_override?number

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

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.5，HighPack 不会改变几何体，也不会额外生成高模。此参数可能影响计费，请参阅 [计费](/zh/api-specification/rodin-gen2-5#计费)。

TAPose?boolean

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

use_original_alpha?boolean

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

preview_render?boolean

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

hd_texture?boolean

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

is_micro?boolean

可选，是否生成微小的表面细节。仅当tier为 `Gen-2.5-Extreme-High` 时允许；其他档位将被拒绝并返回 `INVALID_REQUEST`。

geometry_instruct_mode?string

可选。选择几何生成策略。`creative` 会采用更丰富或更具创意的结构，对输入的严格性要求较低；`faithful` 则更贴近提供的图像和提示。可用性取决于所选tier。

texture_delight?boolean

可选。如果为真，在生成纹理前会从纹理参考图像中移除高光和烘焙光照，以减少生成材质中的光照伪影。

Response Body

`application/json`

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

{  "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"}

输入方式

Image-to-3D

提交一到五个 images。第一张图片用于材质生成。prompt 可选；省略时，服务会从图片推导提示信息。

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.5-Medium' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

Text-to-3D

提交 prompt，并省略 images。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rodin' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'prompt=A small wooden treasure chest with brass trim' \
  --form 'tier=Gen-2.5-Medium' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

Tier

tier 为必传参数

请始终显式传入一个 Gen-2.5 tier。如果省略 tier，接口会回退到 Regular 并生成 Gen-1/1.5 资产。

tier 用于选择生成系列以及模型的细节表现能力。它与下面的网格和纹理参数相互独立：任一 tier 都可以与 schema 允许的任意 mesh_mode、quality 或 texture_mode 组合使用。

Tier	适用场景
`Gen-2.5-Extreme-Low`	快速生成简单资产。
`Gen-2.5-Low`	结构清晰的资产和小型硬表面道具。
`Gen-2.5-Medium`	平衡结构与细节。
`Gen-2.5-High`	更丰富的结构和更平滑的表面。
`Gen-2.5-Extreme-High`	适合需要还原高频细节的资产。

Creative mode

Creative mode（geometry_instruct_mode=creative）在保持输出质量一致的同时，允许更灵活的生成。该模式适用于 Gen-2.5-Medium 及更高 tier。

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

Texture mode

texture_mode 用于选择纹理生成的精细程度。texture_mode 的默认值取决于所选的 tier。

Tier	默认 `texture_mode`
`Gen-2.5-Extreme-Low`	`extreme-low`
`Gen-2.5-Low`	`low`
`Gen-2.5-Medium`	`medium`
`Gen-2.5-High`	`high`
`Gen-2.5-Extreme-High`	`high`

如何生成 12K 纹理

纹理分辨率由 texture_mode 和 addons 共同决定。

项目	纹理分辨率
基础生成	2K
`addons=HighPack`	4K
`texture_mode=extreme-high`	6K
`texture_mode=extreme-high` + `addons=HighPack`	12K

计费

项目	扣费
Gen-2.5 基础生成	`0.5 credits`
`tier=Gen-2.5-Extreme-High`	`+0.5 credits`
`addons` 包含 `HighPack`	`+1.0 credits`
`texture_mode=extreme-high`	`+2.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 仅表示接口已处理请求；只有在 error 缺失或为空且顶层 uuid 非空时，任务才算已受理。400 表示字段或文件无效，401 表示鉴权无效，429 表示触发限流。

Rodin Gen-2.5

201application/json

`application/json`