Rodin Gen-2.5

POST

/api/v2/rodin

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

Authorization

bearer

headerAuthorizationBearer <token>

Request Body

multipart/form-data

body

images*array<>

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

Items1 <= items <= 5

prompt?string

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

提示：推荐在使用 Image-to-3D 时忽略此参数。

用于指导生成的文本提示。Text-to-3D 必填；Image-to-3D 可选。提示词会先生成为图片，因此纯文本请求也可能返回 `IMAGE_CONTENT_VIOLATION`。提示：推荐在使用 Image-to-3D 时忽略此参数。

Lengthlength <= 1024

seed?integer

可选，随机种子。

Range0 <= value <= 65535

mesh_mode?string

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

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

Default"Raw"

Value in"Quad""Raw"

geometry_file_format?string

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

Default"glb"

Value in"glb""usdz""fbx""obj""stl"

material?string

可选，材质类型。

PBR：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。可实现高度真实感，并对动态光照做出物理准确的响应。

Shaded：包含烘焙光照的基础色贴图。

All：同时包含 PBR 和 Shaded 材质。

Hybrid：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。

None：资产不包含材质。

可选，材质类型。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。可实现高度真实感，并对动态光照做出物理准确的响应。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。 - `Hybrid`：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。 - `None`：资产不包含材质。

Default"PBR"

Value in"PBR""Shaded""All""Hybrid""None"

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。

可选。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。

Default"medium"

Value in"high""medium""low""extra-low"

quality_override?integer

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

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

Range500 <= value <= 2000000

tier*string

必填。请选择并显式传入 Gen-2.5 档位。若省略，接口会回退到 Regular 并生成 Gen-1/1.5 资产。

更多信息请参阅 Tier。

此参数可能影响计费，请参阅计费。

必填。请选择并显式传入 Gen-2.5 档位。若省略，接口会回退到 `Regular` 并生成 Gen-1/1.5 资产。更多信息请参阅 [Tier](/zh/api-specification/rodin-gen2-5#tier)。此参数可能影响计费，请参阅 [计费](/zh/api-specification/rodin-gen2-5#计费)。

Default"Regular"

Value in"Gen-2.5-Extreme-Low""Gen-2.5-Low""Gen-2.5-Medium""Gen-2.5-High""Gen-2.5-Extreme-High"

bbox_condition?array<>

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

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

Items3 <= items <= 3

addons?array<>

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

Default[]

TAPose?boolean

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

Defaultfalse

use_original_alpha?boolean

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

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

Defaultfalse

preview_render?boolean

可选。若为真，则在下载列表中提供一张额外的高质量渲染图像。默认值为 false。

若触发 Fast mode，此参数将被忽略。

可选。若为真，则在下载列表中提供一张额外的高质量渲染图像。默认值为 `false`。若触发 [Fast mode](/zh/api-specification/rodin-gen2-5#fast-mode)，此参数将被忽略。

Defaultfalse

hd_texture?boolean

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

Defaultfalse

texture_mode?string

可选。生成模型的纹理模式。

较高的模式通常会产生更丰富、更高分辨率的纹理细节，但耗时更长且可能影响计费。请参阅计费。

legacy：使用旧版纹理管线。

extreme-high：可生成最高 12K 纹理。请参阅如何生成 12K 纹理。

默认值取决于所选的 tier，请参阅纹理模式。

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

Value in"legacy""extreme-low""low""medium""high""extreme-high"

is_micro?boolean

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

提示：我们建议将此参数置空或取用默认值。`

可选，是否生成微小的表面细节。仅当tier为 `Gen-2.5-Extreme-High` 时允许；其他档位将被拒绝并返回 `INVALID_REQUEST`。提示：我们建议将此参数置空或取用默认值。`

Defaultfalse

geometry_instruct_mode?string

可选。选择几何生成策略。creative 会采用更丰富或更具创意的结构，对输入的严格性要求较低；faithful 更注重还原参考图片和提示词，但不一定能带来更贴近输入或质量更高的结果。可用性取决于所选tier。

提示：建议省略此参数，使用默认值。faithful 为实验性选项，未来可能停止支持，不建议用于生产环境。

可选。选择几何生成策略。`creative` 会采用更丰富或更具创意的结构，对输入的严格性要求较低；`faithful` 更注重还原参考图片和提示词，但不一定能带来更贴近输入或质量更高的结果。可用性取决于所选tier。提示：建议省略此参数，使用默认值。`faithful` 为实验性选项，未来可能停止支持，不建议用于生产环境。

Default"creative"

Value in"faithful""creative"

texture_delight?boolean

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

提示：我们建议将此参数置空或取用默认值，除非您有特殊的光照需求。

可选。如果为`true`，在生成纹理前会从纹理参考图像中移除高光和烘焙光照，以减少生成材质中的光照伪影。提示：我们建议将此参数置空或取用默认值，除非您有特殊的光照需求。

Defaultfalse

uhd_texture?boolean

可选。对纹理细节进行额外锐化，可提升细节感知效果，但也可能引入伪影。此参数会可能会影响贴图分辨率，详情参阅贴图分辨率。

Defaultfalse

image_label?array<>

可选。上传的每个图像的查看方向标签，位置匹配到图像。默认值为 ?，列表会填充到图像数量。提交的标签数量不能超过图像数量。超出上传图片数量时，会返回错误 IMAGE_LABEL_LENGTH_TOO_LONG。支持的方向标签有：

Front：F

Front-Left：FL

Front-Right：FR

Back：B

Back-Left：BL

Back-Right：BR

Left：L

Right：R

Up：U

Down：D

Unknown：?。

可选。上传的每个图像的查看方向标签，位置匹配到图像。默认值为 `?`，列表会填充到图像数量。提交的标签数量不能超过图像数量。超出上传图片数量时，会返回错误 IMAGE_LABEL_LENGTH_TOO_LONG。支持的方向标签有： - `Front`：`F` - `Front-Left`：`FL` - `Front-Right`：`FR` - `Back`：`B` - `Back-Left`：`BL` - `Back-Right`：`BR` - `Left`：`L` - `Right`：`R` - `Up`：`U` - `Down`：`D` - `Unknown`：`?`。

Default[]

is_symmetric?string

可选。用于生成几何体的对称性设置。对于应左右镜像的对象，使用“symmetric”；对于姿态或不规则对象，使用“asymmetric”；对于主要对称但需保留细微自然差异的对象，使用“balanced”；使用“unknown”让系统根据提示和输入图像推断模式。

Default"unknown"

Value in"symmetric""balanced""asymmetric""unknown"

soft?boolean

可选。在不改变生成tier的情况下，为最终的几何体生成提示添加平滑边缘。

提示：我们建议将此参数置空或省略此参数。

Defaultfalse

detail_level?integer

可选。控制使用RGB图像条件化的最终几何优化阶段数量。数值越高，保留的视觉细节越多。若省略，则使用默认的优化路径。

提示：我们建议将此参数置空或省略此参数。

Range1 <= value <= 3

quad_normal?boolean

可选。在网格细化过程中，将高分辨率几何细节烘焙为法线贴图。

Defaultfalse

Response Body

application/json

response

error?string

错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 errors。

错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 [errors](/zh/api-specification/errors)。

Value in"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

提交的生成任务的唯一标识符。

Formatuuid

submit_time?string

提交任务的服务器时间。

Formatdate-time

jobs?

一个包含生成过程中执行的各个任务详细信息的工作对象。

consumed?number

本次请求消耗的 credits。

prompt?string

实际用于生成的提示词。

Example Request

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

Example ResponseSchema

{  "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`	适合需要还原高频细节的资产。该 tier 还会返回一个额外的最多千万面数的网格。

几何生成模式

geometry_instruct_mode 用于选择输入如何影响几何生成。faithful 更注重还原参考图片和提示词，但效果因任务而异。

实验性选项：faithful

faithful 未来可能停止支持，不建议用于生产环境。常规生成建议省略 geometry_instruct_mode，使用默认值。

Fast mode

当满足以下条件时，会触发 Fast mode。

tier 不是 Gen-2.5-Extreme-High.
geometry_file_format 为 glb、fbx 或usdz.
mesh_mode 为 Raw.
quality_override <= 20000.

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`

贴图分辨率

纹理分辨率由 texture_mode、uhd_texture 和 addons（HighPack）共同决定。

HighPack 会按下表提高 pack 纹理分辨率。对于 Gen-2.5，它不会改变几何体，也不会额外生成高模。

texture_mode	addons	uhd_texture	分辨率
extreme-low, low, medium, high	[]	false	2K
	[]	true	4K
	HighPack	false	4K
	HighPack	true	8K
extreme-high	[]	false	6K
	[]	true	6K
	HighPack	false	12K
	HighPack	true	12K

计费

项目	扣费
Gen-2.5 基础生成	`0.5 credits`
`tier=Gen-2.5-Extreme-High`	`+0.5 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

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

输入方式Copy Anchor Link

Image-to-3DCopy Anchor Link

Text-to-3DCopy Anchor Link

TierCopy Anchor Link

几何生成模式Copy Anchor Link

Fast modeCopy Anchor Link

Texture modeCopy Anchor Link

贴图分辨率Copy Anchor Link

计费Copy Anchor Link

响应与生命周期Copy Anchor Link

Authorization

Request Body

Response Body

输入方式

Image-to-3D

Text-to-3D

Tier

几何生成模式

Fast mode

Texture mode

贴图分辨率

计费

响应与生命周期