图生模型（H3）

本页列出 H3 产品线下 image_to_model 支持的全部参数。H3 支持两个模型版本：v3.1-20260211 和 v3.0-20250812。

何时使用 H3

• 当你需要高保真几何细节与完整参数控制时，优先使用 H3。
• 如果你已经有四个方向输入图，建议改用 multiview_to_model。

接口地址

参数

必填参数

type: 该字段必须设置为 image_to_model。

file: 指定图像输入。

• type: 表示文件类型。虽然当前不会严格校验，但强烈建议填写正确的文件类型。
• file_token: 从上传接口获得的标识，请参考直接上传部分。与 url 和 object 互斥。
• url: 图像的直链 URL。支持 JPEG 和 PNG，最大 20MB。与 file_token 和 object 互斥。
• object （强烈推荐）: 从上传接口获取的对象信息，请参考 Upload in STS。与 url 和 file_token 互斥。
  • bucket: 通常固定为 tripo-data。
  • key: 返回值中的 resource_uri。

model_version：v3.1-20260211 或 v3.0-20250812。

常用参数

model_seed: 一个 integer 值；若不设置将随机生成。它是模型生成的随机种子。对于 model_version>=v2.0-20240919 或 Turbo-v1.0-20250506，该种子会控制几何生成过程，使用相同种子可得到一致的模型。

enable_image_autofix: bool 值，用于控制是否优化输入图像以提升生成效果。开启后处理时间会更长。默认值为 false。

texture: bool 值，用于启用贴图。设为 false 时会输出不带贴图的基础模型。默认值为 true。设为 false 可少消耗 10 credits；该规则不适用于版本 v1.4-20240625。

进阶参数

texture_seed: 一个 integer 值；若不设置将随机生成。它是 model_version>=v2.0-20240919 或 Turbo-v1.0-20250506 时纹理生成的随机种子。使用相同种子会得到一致的贴图。若希望同一模型生成不同贴图，请保持 model_seed 相同并使用不同的 texture_seed。

texture_alignment: 用于控制 3D 模型贴图对齐策略优先级的 text 值。默认值为 original_image。可选值如下：

• original_image: 优先贴近源图视觉效果。该选项会让贴图更像原图，但可能产生轻微的 3D 一致性偏差。
• geometry: 优先保证 3D 结构准确性。该选项会更贴合模型几何结构，但外观可能与原图略有差异。

texture_quality: 用于控制贴图质量的 text 值。可选 detailed 或 standard。detailed 会提供更高分辨率贴图，在复杂细节上更精细、更真实，适合对视觉保真度要求较高的模型。默认值为 standard。设为 detailed 时会额外消耗 10 credits。

texture_quality=detailed 时的组合规则：

• texture=false, pbr=false：将贴图放大至 4K，PBR 材质将被移除。仅 v3.0-20250812 可用。
• texture=false, pbr=true：基于当前贴图生成 PBR。
• texture=true, pbr=false：重新生成高清贴图，不含 PBR。
• texture=true, pbr=true：重新生成高清贴图并含 PBR。

注意

texture_quality=standard 时，texture=false 与 pbr=false 同时设置不被允许。

pbr: bool 值，用于启用 pbr。设为 false 时会输出不带 pbr 的模型。默认值为 true。

TIP

若该选项为 true，texture 的取值会被忽略并强制视为 true。

smart_low_poly: bool 值，用于控制是否生成具有人为优化拓扑的低模网格。输入复杂度较低时效果最佳。默认值为 false。设为 true 时会额外消耗 10 credits。

Caution

复杂模型存在失败可能。

quad: bool 值，设为 true 可启用四边面网格输出。若 quad=true 且未设置 face_limit，则 face_limit 会默认设为 10000。建议不超过 150,000。设为 true 时会额外消耗 5 credits。

TIP

启用该选项会强制输出为 FBX 模型。

face_limit: 用于限制输出模型面数的 integer 值。若不设置，系统会自适应决定面数。

三角面限制（默认输出）：

模型版本	Standard（geometry_quality=standard）	Ultra（geometry_quality=detailed）
v3.1-20260211	不超过 1,500,000	不超过 2,000,000
v3.0-20250812	不超过 1,000,000	不超过 1,500,000

四边面限制（quad=true）：建议不超过 150,000。

若 smart_low_poly=true，范围应为 1000~20000；若同时 quad=true，范围应为 500~10000。

auto_size: bool 值，用于将模型自动缩放到现实世界尺寸（单位为米）。默认值为 false。

TIP

该参数仅可用于带贴图的模型。

orientation: text 值。设置 orientation=align_image 时，会自动旋转模型以对齐原始图像。默认值为 default。仅在 texture=true 时生效。

compress: 用于指定压缩类型的 text 值。设置为 geometry 时会应用基于几何的压缩以优化输出。默认使用 meshopt 压缩。

generate_parts: 生成分段后的 3D 模型，并使每个部分可编辑。默认值为 false。设为 true 时会额外消耗 20 credits。

TIP

generate_parts 与 texture=true 或 pbr=true 不兼容。若要生成分段，请将 texture=false 且 pbr=false；

generate_parts 也与 quad=true 不兼容。若要生成分段，请将 quad=false。

export_uv: bool 值，用于控制生成过程中是否执行 UV 展开。默认值为 true。

TIP

设为 false 时，生成速度会显著提升且模型体积更小。UV 展开会在贴图阶段完成。

geometry_quality: 用于设置几何质量的 text 值，可选如下；当设为 detailed 时会额外消耗 20 credits：

• Ultra Mode：设置为 detailed 时可获得最高细节，适合复杂且追求真实感的模型。
• Standard Mode：在细节与速度之间保持平衡。默认值为 standard。

返回值

task_id: 成功提交任务后的唯一标识。