Rodin Gen-2
使用 Rodin Gen-2 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"material?string可选，材质类型。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。可实现高度真实感，并对动态光照做出物理准确的响应。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。 - `Hybrid`：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。 - `None`：资产不包含材质。
"PBR""PBR""Shaded""All""Hybrid""None"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。
"medium""high""medium""low""extra-low"quality_override?integer可选。Gen-2 的自定义目标面数，取值范围为 500 到 1000000，提交后优先于 `quality`。`Quad` 模式另有 200000 的上限；`Raw` 模式最高支持 1000000。
500 <= value <= 1000000tier*"Gen-2"必填。请显式设置该字段为 `Gen-2`。若省略，接口会回退到 `Regular` 并生成 Gen-1/1.5 资产。
"Regular""Gen-2"bbox_condition?array<>可选。控制生成模型的最大尺寸。请严格按宽度（X 轴）、高度（Y 轴）、长度（Z 轴）的 `(x, y, z)` 顺序提供三个整数。参阅 [BBOX Control](/zh/api-specification/bbox-control)。
3 <= items <= 3addons?array<>可选付费附加项。将 pack 纹理从 2K 升级到 4K。对于 Gen-2，HighPack 不会改变几何体，也不会额外生成高模。
[]TAPose?boolean可选，对于类人型模型，使用适合动画的 T-pose 或 A-pose 参考姿态生成结果。
falseuse_original_alpha?boolean可选，是否使用原始 alpha 通道。默认值为 `false`。当原图无有效的 alpha 通道时，此参数无效。
falsepreview_render?boolean可选，若为真，则在下载列表中提供一张额外的高质量渲染图像。默认值为 false。
falsehd_texture?boolean可选。启用额外的纹理超分辨率和增强处理步骤。这可以提升细节清晰度，但也可能引入伪影。该功能不会决定最终的 2K 或 4K 打包分辨率；
falsesoft?boolean可选。在不改变生成tier的情况下，为最终的几何体生成提示添加平滑边缘。
提示：我们建议将此参数置空或省略此参数。
falsedetail_level?integer可选。控制使用RGB图像条件化的最终几何优化阶段数量。数值越高，保留的视觉细节越多。若省略，则使用默认的优化路径。
提示：我们建议将此参数置空或省略此参数。
1 <= value <= 3is_symmetric?string可选。用于生成几何体的对称性设置。对于应左右镜像的对象，使用“symmetric”；对于姿态或不规则对象，使用“asymmetric”；对于主要对称但需保留细微自然差异的对象，使用“balanced”；使用“unknown”让系统根据提示和输入图像推断模式。
"unknown""symmetric""balanced""asymmetric""unknown"quad_normal?boolean可选。在网格细化过程中，将高分辨率几何细节烘焙为法线贴图。
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=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 |
各项费用累加计算。基础生成仅需 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 表示触发限流。