Rodin Gen-1/1.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

必填。Rodin Gen-1/1.5 生成档位：`Sketch`、`Regular`、`Detail` 或 `Smooth`。默认为 `Regular`。

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-1/1.5 的预设目标面数，默认为 `medium`。两种网格模式使用相同映射： - `Quad`：`high` 50000、`medium` 18000、`low` 8000、`extra-low` 4000； - `Raw`：`high` 50000、`medium` 18000、`low` 8000、`extra-low` 4000。

quality_override?number

可选。Gen-1/1.5 的自定义目标面数，取值范围为 500 到 200000。提交后优先于 quality。

seed?integer

可选，随机种子。

condition_mode?string

可选。多图生成模式，此参数仅用于Gen-1/1.5。默认为 `concat`。 - `fuse`：融合所有输入图像，生成单个模型。 - `concat`：将所有上传图片视为单个物体的多视角图片。

bbox_condition?array<>

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

addons?array<>

可选付费附加项。HighPack 始终把 pack 纹理从 2K 升级到 4K。对于 `Quad` 模式的 `Sketch` 和 `Regular`，显式传入不超过 100000 的 `quality_override` 时，还会请求面数约为该值 16 倍的高模。对于 `Detail` 和 `Smooth`，HighPack 只改变纹理分辨率。

TAPose?boolean

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

use_original_alpha?boolean

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

preview_render?boolean

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

mesh_simplify?boolean

可选。用于控制Raw网格是否被简化。此参数仅用于Gen1/1.5且mesh_mode为Raw时有效。

mesh_smooth?boolean

可选。用于控制生成的四边面网格是否进行平滑处理。此参数仅用于Gen1/1.5且mesh_mode为Quad时有效。

Response Body

`application/json`

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

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

输入

从 Sketch、Regular、Detail 或 Smooth 中选择一个 tier。Image-to-3D 提交一到五个 images；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 'images=@./input.png' \
  --form 'tier=Regular' \
  --form 'mesh_mode=Quad' \
  --form 'quality=medium'

多图行为

condition_mode=concat 把上传图片视为同一物体的多个视角。
condition_mode=fuse 融合可能包含不同物体的多张图片中的特征。
mesh_mode 可取 Quad 或 Raw，默认为 Quad。
quality 用于选择预设目标面数，默认为 medium：
- Quad：high 50000、medium 18000、low 8000、extra-low 4000。
- Raw：high 50000、medium 18000、low 8000、extra-low 4000。
quality_override 用于设置 500 到 200000 之间的自定义目标面数，提交后优先于 quality。

有两个选项仅适用于该系列：mesh_simplify 用于简化 Raw 网格，默认开启；mesh_smooth 用于平滑 Quad 网格，默认关闭。Add-on 的可用性取决于所选 tier。

HighPack 始终把 pack 纹理从 2K 升级到 4K。对于 Quad 模式的 Sketch 和 Regular，显式设置不超过 100000 的 quality_override 时，还会请求面数约为该值 16 倍的高模。对于 Detail 和 Smooth，HighPack 只改变纹理分辨率。

计费

项目	扣费
Gen-1/1.5 基础生成	`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 表示触发限流。