Rodin Gen-1/1.5
使用 Rodin Gen-1/1.5 tier 生成 3D asset。
根据图片和/或文本提示生成网格与纹理。
bearerAuthorizationBearer <token>multipart/form-data- body
images*array<>用于生成的图片，最多 5 张。请求体中的上传顺序会被保留。Image-to-3D 至少需要一张图片；Text-to-3D 不提交此字段。
1 <= items <= 5prompt?string用于指导生成的文本提示。Text-to-3D 必填；Image-to-3D 可选。提示词会先生成为图片，因此纯文本请求也可能返回 `IMAGE_CONTENT_VIOLATION`。 提示：推荐在使用 Image-to-3D 时忽略此参数。
length <= 1024seed?integer可选，随机种子。
0 <= value <= 65535mesh_mode?string可选，控制生成模型的拓扑结构。`Raw` 表示三角面拓扑，`Quad` 表示四边面拓扑。默认值取决于所选的 `tier`：Gen-2.5 tiers 默认使用 `Raw`，其他 tiers 默认使用 `Quad`。
"Quad""Quad""Raw"geometry_file_format?string可选，控制生成模型的文件格式。
"glb""glb""usdz""fbx""obj""stl"condition_mode?string可选。多图生成模式，此参数仅用于Gen-1/1.5。默认为 `concat`。 - `fuse`： 融合所有输入图像，生成单个模型。 - `concat`： 将所有上传图片视为单个物体的多视角图片。
"concat""fuse""concat"material?string可选，材质类型。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。可实现高度真实感，并对动态光照做出物理准确的响应。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。 - `Hybrid`：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。 - `None`：资产不包含材质。
"PBR""PBR""Shaded""All""Hybrid""None"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。
"medium""high""medium""low""extra-low"quality_override?integer可选。Gen-1/1.5 的自定义目标面数，取值范围为 500 到 200000。提交后优先于 quality。
500 <= value <= 200000tier*string必填。Rodin Gen-1/1.5 生成档位：`Sketch`、`Regular`、`Detail` 或 `Smooth`。默认为 `Regular`。
"Regular""Regular""Detail""Smooth""Sketch"bbox_condition?array<>可选。控制生成模型的最大尺寸。请严格按宽度（X 轴）、高度（Y 轴）、长度（Z 轴）的 `(x, y, z)` 顺序提供三个整数。参阅 [BBOX Control](/zh/api-specification/bbox-control)。
3 <= items <= 3addons?array<>可选付费附加项。HighPack 始终把 pack 纹理从 2K 升级到 4K。对于 `Quad` 模式的 `Sketch` 和 `Regular`，显式传入不超过 100000 的 `quality_override` 时，还会请求面数约为该值 16 倍的高模。对于 `Detail` 和 `Smooth`，HighPack 只改变纹理分辨率。
[]TAPose?boolean可选，对于类人型模型，使用适合动画的 T-pose 或 A-pose 参考姿态生成结果。
falseuse_original_alpha?boolean可选，是否使用原始 alpha 通道。默认值为 `false`。当原图无有效的 alpha 通道时，此参数无效。
falsepreview_render?boolean可选，若为真，则在下载列表中提供一张额外的高质量渲染图像。默认值为 false。
falsemesh_simplify?boolean可选。用于控制Raw网格是否被简化。此参数仅用于Gen1/1.5且mesh_mode为Raw时有效。
truemesh_smooth?boolean可选。用于控制生成的四边面网格是否进行平滑处理。此参数仅用于Gen1/1.5且mesh_mode为Quad时有效。
falseapplication/json- response
error?string错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 [errors](/zh/api-specification/errors)。
"NO_SUCH_TASK""ASSET_NOT_AVAILABLE""IMAGE_LABEL_LENGTH_TOO_LONG""INVALID_REQUEST""API_NO_ACTIVE_SUBSCRIPTION""API_SUBSCRIPTION_PLAN_TOO_LOW""API_PARALLELISM_LIMIT_REACHED""API_INSUFFICIENT_FUNDS""API_OBJECT_NOT_FOUND_ON_IMAGE""IMAGE_CONTENT_VIOLATION""PERMISSION_DENIED""API_UNKNOWN"message?string成功消息或详细错误信息。
uuid?string提交的生成任务的唯一标识符。
uuidsubmit_time?string提交任务的服务器时间。
date-timejobs?一个包含生成过程中执行的各个任务详细信息的工作对象。
consumed?number本次请求消耗的 credits。
prompt?string实际用于生成的提示词。
curl -X POST 'https://api.hyper3d.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：high50000、medium18000、low8000、extra-low4000。Raw：high50000、medium18000、low8000、extra-low4000。
-
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 |
各项费用累加计算。基础生成仅需 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 表示触发限流。