常见问题 (FAQ)

Hi3D API 使用问题

调用 API 需要满足哪些前提条件？

在进行正式 API 调用之前，请先登录开放平台，激活测试资源包或购买生产资源包，并创建 API Key。

如何购买 API 资源包？

登录后，前往平台的资源包页面进行购买。

如何获取 API Key？

登录后，在 API Key 管理页面创建和管理您的 API Key。

如何进行 API 调用？

使用 HTTPS 和 POST 方法。

身份验证：在 Authorization 头中放入您的 API Key 来调用获取 Token 接口。
创建任务：调用创建任务接口时在 Authorization 头中包含 Token，并提供必需的 body 参数，如请求类型（仅几何 / 分阶段 / 一次性）、图像输入类型和文件（单视图 / 多视图）、模型分辨率、目标多边形数量和输出格式。

完整的参数详情请参见 API 参考文档。

并发与速率限制？

默认 30 个并发任务。如需更高并发，请联系 apicontact@hi3d.ai。

如何查看任务状态和下载结果？

轮询任务或配置 Webhook 以接收状态更新。当 status=success 时，响应包含生成的资产 ID、封面/预览信息和下载 URL（模型 + 纹理）。

API 是否支持批量生成？

每次调用只创建一个任务。

如何排查常见错误？

如果问题仍然存在，请按照错误消息指引或联系 apicontact@hi3d.ai。

调用失败会扣除积分吗？

不会。对于服务器故障/超时/参数验证失败，积分会退还或不扣除（超时阈值：60 分钟）。

请查看错误代码了解失败类型。

生成模式和类型？

模式：图生3D、图生3D浮雕、3D模型拆件、3D模型多色。
类型：
- 单图/多图生3D：仅几何生成；仅纹理生成（可使用 pbr）；几何&纹理一次性生成（可使用 pbr）。
- 图生3D浮雕：仅支持一次性生成。
- 3D模型拆件：仅支持一次性生成。
- 3D模型多色：仅支持一次性生成。

输入图像/模型格式和大小限制？

输入图像数量限制？

因模式而异：

支持的分辨率？

通用模型：v1.5（512³、1024³、1536³、1536³ Pro）；v2.0（1536³、1536³ Pro）；v2.1（1536fast、1536pro）；v3.0（2048quality、2048master）。
肖像模型：v1.5（1536）；v2.0（1536pro）；v2.1（profast、1536pro）。
深度模型：Base、Pro。
更高的分辨率会产生更多细节和更大的文件，推理时间也更长。

多边形数量？

您可以设置 100,000-5,000,000 范围内的目标多边形数量。不同分辨率对应的推荐面数不一致：

输出格式？