Hyper3DHyper3D Docs
API 规范

生成低模

从 Rodin 资产、上传模型、图像或文本生成低模,并查询进度、下载结果。

POST
/api/v2/polygen

Authorization

bearer
headerAuthorizationBearer <token>

Request Body

multipart/form-data
  1. body
asset_id?string
Formatuuid
model?file
Formatbinary
transfer_texture?boolean
Defaulttrue
images?array<>
Items1 <= items <= 5
prompt?string
image_label?array<>
Default[]
face_count?integer

可选。 目标面数(200–10,000)。省略时,上传模型的目标面数为 4,000,其他输入自动确定面数。

Range200 <= value <= 10000
mesh_mode?string
Default"Quad"
Value in"Quad""Raw""NGon"
geometry_file_format?string

可选。 输出文件格式。默认为 obj。

Default"obj"
Value in"glb""usdz""fbx""obj""stl"
material?string
Default"None"
Value in"PBR""Shaded""All""Hybrid""None"
resolution?string
Default"Basic"
Value in"Basic""High"
texture_mode?string
Default"medium"
Value in"legacy""extreme-low""low""medium""high""extreme-high"
uhd_texture?boolean

Response Body

application/json
  1. response
message?string

成功消息或详细错误信息。

uuid?string
Formatuuid
submit_time?string

提交任务的服务器时间。

Formatdate-time
jobs?
consumed?number

本次请求消耗的credits。

error?ApiGeneratePolygenError

任务无法提交时返回的错误码,成功时省略。

Value in"INVALID_REQUEST""NO_SUCH_TASK""PERMISSION_DENIED""ASSET_NOT_AVAILABLE""NO_ACTIVE_SUBSCRIPTION""INSUFFICIENT_FUNDS""UNKNOWN"
Example Request
curl -X POST 'https://api.hyper3d.com/api/v2/polygen'
Example Response
{  "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,  "error": "INVALID_REQUEST"}

POST /api/v2/polygen 可以从已有的 Rodin 资产、模型文件、参考图像或文本描述生成 Smart Low Poly 低模。生成在后台进行:提交任务后查询进度,完成后下载结果。请求需要使用具有 Full API 访问权限的 Bearer API key。

选择输入方式

根据手头的素材选择输入。上传文件时使用 multipart/form-data。

输入提交内容纹理
已完成的 Rodin 任务将任务顶层 uuid 作为 asset_id设置 material 后生成
模型文件通过 model 上传文件从原模型转移
参考图像通过重复的 images 字段上传 1–5 张设置 material 后生成
文本描述仅提供 prompt设置 material 后生成

选择网格和导出格式

  • face_count:目标面数,范围为 200–10,000。省略时,上传模型的目标面数为 4,000,其他输入自动确定面数。
  • mesh_mode:Quad(默认)生成四边面,Raw 生成三角面,NGon 生成多边形面。
  • geometry_file_format:支持 obj(默认)、glb、usdz、fbx 和 stl。glb、usdz 和 fbx 会将纹理打包进模型文件。

生成纹理

从资产、图像或文本生成时,默认仅生成几何。如需同时生成纹理,将 material 设为 PBR、Shaded、Hybrid 或 All。上传模型的纹理处理方式不同,请参阅从上传模型生成。

texture_mode 决定纹理的精细程度,可选 extreme-low、low、medium(默认)、high 和 extreme-high。档位越高,纹理细节越丰富,耗时也越长。legacy 使用旧版纹理管线。

设置 uhd_texture=true 可以锐化纹理细节。如果结果出现伪影,关闭此选项即可。

贴图分辨率

生成纹理的分辨率由 texture_mode、uhd_texture 和 resolution 共同决定。

resolution 默认为 Basic;High 需要高分辨率导出权限。

texture_moderesolutionuhd_texture=falseuhd_texture=true
extreme-low、low、medium、highBasic2K*4K
extreme-low、low、medium、highHigh4K*8K
extreme-highBasic6K6K
extreme-highHigh12K12K

* 仅影响 base color 贴图,法线、金属度、粗糙度贴图的分辨率不变。

提交生成任务

从 Rodin 资产生成

将已完成的 Rodin Gen-2 或 Gen-2.5 任务的顶层 uuid 作为 asset_id 传入。从上传模型开始的任务(例如通过 model 提交的 PolyGen 或绑定任务)不能作为 asset_id。如需继续简化这类结果,请下载后通过 model 上传。

下方示例仅生成几何。设置 material 后,PolyGen 会使用源任务的输入图像和提示词生成纹理。如需更换参考,可以上传 images 或传入新的 prompt。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'asset_id=123e4567-e89b-12d3-a456-426614174000' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

从上传模型生成

通过 model 上传 obj、glb、stl、fbx、usd、usda、usdz 或 usdc 文件。PolyGen 会简化网格,并将原有纹理转移到低模上。如果只需要几何,设置 transfer_texture=false。

上传模型时不会生成新纹理,因此 material、texture_mode、uhd_texture 和 prompt 不起作用。resolution 决定转移后的贴图尺寸:Basic 导出 2K,High 导出 4K。也可以上传 images,作为网格细化的参考。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'model=@./model.glb' \
  --form 'transfer_texture=true' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

从图像生成

通过重复的 images 字段上传 1–5 张图像,例如 PNG、JPEG 或 WebP 文件。PolyGen 会根据这些图像生成网格,并将其作为纹理参考。

下方示例上传物体的正面和背面图,并生成 PBR 纹理。image_label 是可选的 JSON 数组,按上传顺序标注视角:["F","B"] 表示第一张是正面、第二张是背面。可以用 prompt 补充图像中不明显的细节,例如表面材质。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'images=@./front.png' \
  --form 'images=@./back.png' \
  --form 'image_label=["F","B"]' \
  --form 'prompt=A small wooden toy robot with a square head and short arms.' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000' \
  --form 'material=PBR'

从文本生成

在 prompt 中描述物体,最多 1,024 个字符。PolyGen 会先根据描述生成参考图,再据此生成低模。下方示例描述了一个木制玩具机器人,仅生成几何。

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'prompt=A small wooden toy robot with a square head and short arms.' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

等待完成并下载

提交成功后,响应会返回新任务的标识:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
    "uuids": ["123e4567-e89b-12d3-a456-426614174001"],
    "subscription_key": "123e4567-e89b-12d3-a456-426614174002"
  }
}

如果响应中包含 error,说明任务没有创建,请参阅处理提交错误。

  1. 将 jobs.subscription_key 传给查询任务状态,轮询直到所有 job 都变为 Done。如果有 job 返回 Failed,该任务不会产生结果。
  2. 将顶层 uuid 作为 task_uuid 传给下载结果,再通过返回的链接下载文件。

价格

每个 PolyGen 任务费用为 0.5 credits,扣费金额见响应中的 consumed。

处理提交错误

字段无法解析或未通过校验时,API 返回 HTTP 400。其他情况被拒绝时仍返回 HTTP 201,响应中的 error 为错误码,message 说明原因。API 报告错误的整体方式请参阅错误。

错误码含义与处理方式
INVALID_REQUEST请求缺少输入、同时传入了 asset_id 和 model,或包含无效的文件或取值。具体问题见 message。
NO_SUCH_TASKasset_id 没有对应的任务。请使用任务顶层的 uuid,而不是 job UUID 或 subscription key。
ASSET_NOT_AVAILABLE源任务尚未完成或不能复用。等待任务完成,或下载模型后通过 model 上传。
PERMISSION_DENIED确认 API key 具有 Full API 访问权限、源资产属于你的账号,以及设置 resolution=High 时具备高分辨率导出权限。
INSUFFICIENT_FUNDS余额不足。补充 credits 后重新提交。