生成低模
从 Rodin 资产、上传模型、图像或文本生成低模,并查询进度、下载结果。
bearerAuthorizationBearer <token>multipart/form-data- body
asset_id?string**与 `model` 互斥。** 已完成的 Rodin 资产的顶层任务 UUID。请核对[源资产要求](/zh/api-specification/polygen#从-rodin-资产生成)。省略 `images` 时,PolyGen 会复用源资产的输入图像作为纹理参考。
uuidmodel?file**与 `asset_id` 互斥。** 待简化的网格文件,支持 `obj`、`glb`、`stl`、`fbx`、`usd`、`usda`、`usdz`、`usdc`。PolyGen 会简化网格并转移原有纹理;将 `transfer_texture` 设为 `false` 时仅生成几何。
binarytransfer_texture?boolean**可选。** 将上传模型的原有纹理转移到低模,默认为 `true`。仅在传入 `model` 时生效。
trueimages?array<>通过重复的 multipart `images` 字段上传 1–5 张图像(PNG、JPEG、WebP)。 与 `model` 配合时,作为可选的网格细化参考;与 `asset_id` 配合时,替换纹理参考;两者都省略时,用于网格生成和纹理参考。如需生成纹理,还需设置 `material`。
1 <= items <= 5prompt?string**仅在文生 3D 时必填。** 传入 `images`、`asset_id` 或 `model` 时,可以省略此字段。 - **不传 `images`、`asset_id` 和 `model`:** 提供不超过 1,024 个字符且不能仅含空白的描述。PolyGen 会先根据描述生成参考图,再生成 3D 模型。 - **传入 `images`,不传 `asset_id` 或 `model`:** 可用 `prompt` 补充参考图,指导图生 3D 和纹理生成(如开启)。省略 `prompt` 时使用通用的 3D 模型提示词。 - **传入 `asset_id`:** 开启纹理生成时,可用 `prompt` 指导新纹理。省略 `prompt` 时沿用源资产的提示词(如有)。 - **传入 `model`:** PolyGen 忽略 `prompt`。
image_label?array<>**可选。** 以 JSON 数组提交视角标签,按上传顺序与 `images` 一一对应。缺少的标签补为 `?`(未知)。标签数量超过上传图像数量时返回 `INVALID_REQUEST`。未上传图像时保留源资产的视角标签。支持的方向: - 前:`F` - 左前:`FL` - 右前:`FR` - 后:`B` - 左后:`BL` - 右后:`BR` - 左:`L` - 右:`R` - 上:`U` - 下:`D` - 未知:`?`
[]face_count?integer可选。 目标面数(200–10,000)。省略时,上传模型的目标面数为 4,000,其他输入自动确定面数。
200 <= value <= 10000mesh_mode?string**可选。** 网格拓扑: - `Quad` 为四边面。 - `Raw` 为三角面。 - `NGon` 为多边形面。 默认为 `Quad`。
"Quad""Quad""Raw""NGon"geometry_file_format?string可选。 输出文件格式。默认为 obj。
"obj""glb""usdz""fbx""obj""stl"material?string**可选。** 默认为 `None`。对于资产、图像或文本输入,`None` 仅生成几何;`PBR`、`Shaded`、`Hybrid` 和 `All` 会生成并导出纹理。上传 `model` 时忽略此参数,默认转移原模型纹理。
"None""PBR""Shaded""All""Hybrid""None"resolution?string**可选。** 输出贴图的分辨率设置,默认为 `Basic`。`High` 提高导出分辨率,需要高分辨率导出权限。生成新纹理时,最终分辨率还取决于纹理模式和锐化设置。请参阅 [贴图分辨率](/zh/api-specification/polygen#贴图分辨率)。仅生成几何时忽略。
"Basic""Basic""High"texture_mode?string**可选。** 生成模型的纹理模式。较高的模式通常会产生更丰富、更高分辨率的纹理细节,但耗时更长。 - `legacy`:使用旧版纹理管线。 - `extreme-high`:可生成最高 12K 纹理。请参阅 [贴图分辨率](/zh/api-specification/polygen#贴图分辨率)。 默认为 `medium`。上传 `model` 或设置 `material=None` 时忽略。
"medium""legacy""extreme-low""low""medium""high""extreme-high"uhd_texture?boolean**可选。** 锐化纹理细节。如果结果出现伪影,关闭此选项即可。除 `extreme-high` 模式外,开启后贴图分辨率翻倍。该参数仅影响 base color 贴图的分辨率,不会更改其他贴图(法线、金属度、粗糙度)的分辨率。请参阅[贴图分辨率](/zh/api-specification/polygen#贴图分辨率)。上传 `model` 或设置 `material=None` 时忽略。
application/json- response
message?string成功消息或详细错误信息。
uuid?string新低模任务的 UUID。将其作为 `task_uuid` 调用 `POST /api/v2/download` 下载结果。
uuidsubmit_time?string提交任务的服务器时间。
date-timejobs?已提交的作业。将 `subscription_key` 传给 `POST /api/v2/status` 查询状态。
consumed?number本次请求消耗的credits。
error?ApiGeneratePolygenError任务无法提交时返回的错误码,成功时省略。
"INVALID_REQUEST""NO_SUCH_TASK""PERMISSION_DENIED""ASSET_NOT_AVAILABLE""NO_ACTIVE_SUBSCRIPTION""INSUFFICIENT_FUNDS""UNKNOWN"curl -X POST 'https://api.hyper3d.com/api/v2/polygen'{ "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_mode | resolution | uhd_texture=false | uhd_texture=true |
|---|---|---|---|
extreme-low、low、medium、high | Basic | 2K | *4K |
extreme-low、low、medium、high | High | 4K | *8K |
extreme-high | Basic | 6K | 6K |
extreme-high | High | 12K | 12K |
* 仅影响 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,说明任务没有创建,请参阅处理提交错误。
- 将
jobs.subscription_key传给查询任务状态,轮询直到所有 job 都变为Done。如果有 job 返回Failed,该任务不会产生结果。 - 将顶层
uuid作为task_uuid传给下载结果,再通过返回的链接下载文件。
价格
每个 PolyGen 任务费用为 0.5 credits,扣费金额见响应中的 consumed。
处理提交错误
字段无法解析或未通过校验时,API 返回 HTTP 400。其他情况被拒绝时仍返回 HTTP 201,响应中的 error 为错误码,message 说明原因。API 报告错误的整体方式请参阅错误。
| 错误码 | 含义与处理方式 |
|---|---|
INVALID_REQUEST | 请求缺少输入、同时传入了 asset_id 和 model,或包含无效的文件或取值。具体问题见 message。 |
NO_SUCH_TASK | asset_id 没有对应的任务。请使用任务顶层的 uuid,而不是 job UUID 或 subscription key。 |
ASSET_NOT_AVAILABLE | 源任务尚未完成或不能复用。等待任务完成,或下载模型后通过 model 上传。 |
PERMISSION_DENIED | 确认 API key 具有 Full API 访问权限、源资产属于你的账号,以及设置 resolution=High 时具备高分辨率导出权限。 |
INSUFFICIENT_FUNDS | 余额不足。补充 credits 后重新提交。 |