帮你快速理解、总结文档立即下载
文档中心>大模型服务平台 TokenHub>调用指南>3D 生成模型>混元调用指南>HY-3d-polygen-image 调用指南

HY-3d-polygen-image 调用指南

最近更新时间：2026-09-18 15:30:30
本文档已由 AI 辅助审校
我的收藏

本页目录：

简介

HY-3d-polygen-image 接口，基于输入的图片，通过大模型算法，生成低面片且布线更规整的3D 模型。

对接说明

1. 获取 API Key

1. 进入 API Key 管理 页面，单击创建 API Key。操作详情请参见 创建 API Key。
2. 创建完成后，请您务必复制并妥善保管 API Key，在后续配置到工具的流程中将会使用该信息。

说明：
每个账户的密钥都只能当前账户查询，主账户的密钥信息子账户是看不到，子账户如果需要调用接口，需要使用账户自行创建密钥信息。
如果子账户没有办法创建，可能是没有权限创建密钥，需要主账户授权，主账户登录之后点击用户列表，在对应的子账户后面选择授权，会弹出关联策略的弹窗，输入授权策略名称之后搜索，选择对应的策略点击确认。
授权策略：QcloudTokenhubFullAccess

2. 并发额度

默认提供1个并发，代表最多能同时处理1个已提交的任务，上一个任务处理完毕后，才能开始处理下一个任务。
并发任务数：表示在调用对应服务的时段内最大可运行的任务数，该任务未完成时，无法提交下一个任务，该任务完成后，可提交下一个任务。

接口文档

提交图生3D 智能减面任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
模型名称。默认为 hy-3d-polygen-image。
示例值：hy-3d-polygen-image
image_url
是
string
图片 URL，必须为 jpeg/jpg/png/webp 格式，分辨率大于128×128，大小小于10MB。
num_of_faces
否
int
目标面数，默认10000，范围100～20000。不填或填0代表默认。
polygon_type
否
string
多边形类型，可选：triangle（默认）或 quadrilateral。
disable_normalization
否
bool
是否禁用归一化，默认 false。设置为 true 则不进行归一化。
输出参数
参数名称
类型
描述
id
string
任务 id（有效期24小时）。
示例值：1315932989749215232
request_id
string
唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
object
string
返回对象类型。3d 任务固定返回 3d_job。
created_at
integer
任务创建时间。
status
string
completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。
示例值：completed

查询图生3D 智能减面任务

输入参数
参数名称
必选
类型
描述
model
是
string
模型名称。默认为 hy-3d-polygen-image。
示例值：hy-3d-polygen-image
id
是
string
任务 id。
示例值：1357237233311637504
输出参数
参数名称
类型
描述
request_id
string
唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
object
string
返回对象类型。3d 任务固定返回 3d_job。
created_at
int
创建时间（Unix 时间戳）。
status
string
completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。
示例值：completed
data
array
生成结果数组（仅状态为 completed 时返回），包含生成的 3d 模型文件及相关资源信息。
data[n].fbx_url
string
智能减面后的低面数 FBX 格式3D 模型下载 URL（有效期1天）。
data[n].obj_url
string
智能减面后的低面数 OBJ 格式3D 模型下载 URL（有效期1天）。
data[n].glb_url
string
智能减面后的低面数 GLB 格式3D 模型下载 URL（有效期1天）。
data[n].image_url
string
减面生成模型的渲染图片 URL（有效期1天）。
data[n].quads_info
string
四边面信息（JSON 字符串），仅当 polygon_type=quadrilateral 时返回，包含点数、面数及坐标信息。
error
object
错误信息（仅状态为 failed 时返回）。
error.code
string
错误码。
error.message
string
错误信息。
error.type
string
错误类型。

示例

提交图生3D 智能减面任务

输入示例
curl --location --request POST 'https://tokenhub.tencentmaas.com/v1/api/3d/submit' \\
--header "Authorization: Bearer ${APIKEY}" \\
--header 'Content-Type: application/json' \\
--data-raw '{
  "model": "hy-3d-polygen-image",
"image_url": "https://example.com/model.jpg"
}'
输出示例
{
  "created_at": 1787890699,
  "id": "xxxxx",
  "object": "3d_job",
  "request_id": "75c28fde-6abe-4fa5-973a-xxxxx",
  "status": "queued"
}

查询图生3D 智能减面任务

输入示例
curl --location --request POST 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\
--header "Authorization: Bearer ${APIKEY}" \\
--header 'Content-Type: application/json' \\
--data-raw '{
  "model": "hy-3d-polygen-image",
  "id": "id"
}'
输出示例
{
    "created_at": 1787814686,
    "object": "3d_job",
    "request_id": "9f97cfa0-2939-46e6-a27d-xxx",
	"data": [
	    {
	      "fbx_url": "https://example.com/model.fbx",
	      "glb_url": "https://example.com/model.glb",
	      "image_url": "https://example.com/model.jpg",
	      "obj_url": "https://example.com/model.obj",
	      "quads_info": ""
	      }],
    "status": "completed"
}

错误码

错误码
HTTP 状态码
说明
InvalidParameter
400
请求参数错误（如 model 缺失、未提供3D 模型 URL 等）
MissingParameter
400
缺少必填参数
FailedOperation
500
任务执行失败
InternalError
500
内部错误
FailedOperation.JobNotExist
500
任务不存在或已过期

中国站