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

Hi3D 调用指南

最近更新时间：2026-08-28 20:35:48
我的收藏

本页目录：

简介

hi3d-2.1模型，根据输入的图片智能生成3d。

对接说明

1. 获取 API Key

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

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

2. 并发额度

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

接口文档

提交 hi3d 任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
hi3d 模型名称。默认为 hi3d-2.1。
示例值：hi3d-2.1
request_type
否
int
请求类型：
1=仅生成几何(mesh)，
2=基于已有几何生成纹理(texture)（hi3d-2.1暂不支持贴纹理），
3=一次性生成几何+纹理(both)。默认 3
images
否
string
单图 URL（与 image_url/image_base64/multi_images 三选一）
image_url
否
string
单图 URL（与 image_base64/multi_images 三选一）
image_base64
否
string
单图 Base64 编码（与 image_url/multi_images 三选一）
multi_images
否
string[]
多视图 URL 列表，最多 4 张（前/后/左/右视图），与单图参数互斥
multi_images_bit
否
string
多视图位图，长度必须为4，由 '0'/'1' 组成。'1'的数量必须与 multi_images 数量匹配。示例："1010" 代表前视图+左视图
resolution
否
string
分辨率，可选项：1536fast、1536pro
hi3d-2.1 默认：1536pro
pbr
否
int
PBR 开关：1=开启(默认)，0=关闭。仅 v2.1 支持
shading
否
float
去光影程度：0.0~1.0（十分位），默认 0.5。仅 v2.1 支持
face
否
int
模型面数，范围 100000~2000000
推荐值：
分辨率：512，推荐500,000面数
分辨率：1024，推荐1,000,000面数
分辨率：1536、1536pro、1536fas，推荐2,000,000面数
format
否
int
输出格式：
1=obj(默认)
2=glb
3=stl
4=fbx
5=usdz
6=3mf
输出参数
参数名称
类型
描述
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

查询 hi3d 任务

输入参数
参数名称
必选
类型
描述
model
是
string
hi3d 模型名称。默认为 hi3d-2.1。
示例值：hi3d-2.1
id
是
string
任务 id。
示例值：1357237233311637504
输出参数
参数名称
类型
描述
status
string
completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。
示例值：completed
request_id
string
唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
data.url
string
生成物下载 URL（任务完成时返回，有效期1小时）
data.cover_url
string
生成物封面图 URL（任务完成时返回，有效期1小时）
object
string
返回对象类型。3d 任务固定返回 3d_job。
created_at
integer
任务创建时间。
completed_at
integer
任务完成时间。

示例

提交 hi3d 任务

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

查询 hi3d 任务

输入示例
curl --location --request POST 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\
--header "Authorization: Bearer ${APIKEY}" \\
--header 'Content-Type: application/json' \\
--header 'Connection: keep-alive' \\
--data-raw '{
  "model": "hi3d-2.1",
  "id": "ID"
}'
输出示例
{
  "created_at": 1787892116,
  "data": {
    "cover_url": "https://example.com/lee.jpg",
    "url": "https://example.com/lee.jpg"
  },
  "object": "3d_job",
  "request_id": "4ba8a00b-ebb0-458d-bae2-xxxxx",
  "status": "completed"
}

常见错误码

error.code
error.message
说明
FailedOperation.JobNotExist
任务不存在。
查询的任务 ID 无效或已过期
FailedOperation.GenerateFailed
generate failed
生成失败（超时或模型无法解析），所耗积分已退还
FailedOperation.BalanceNotEnough
balance is not enough
积分余额不足
InvalidParameter.FileSizeExceedsLimit
Upload file size exceeds limit
文件超过 20MB
InvalidParameter.FaceNotValid
Face not valid
面数不合理（100000~2000000）
InvalidParameter.ResolutionNotValid
Resolution not valid
分辨率不合理
InvalidParameter.RequestTypeNotSupport
request type not support
请求类型不支持
InvalidParameter.ImageFormatError
images only allow png jpeg jpg webp
图片格式错误
InvalidParameter.ImageConflict
both images and multi images provided
不能同时上传单图和多视图
InvalidParameter.ImageRequired
images or multi images required
必须上传图片
InvalidParameter.MultiImagesExceedsLimit
multi images count exceeds limit
多视图最多4张
InvalidParameter.MultiImagesBitLengthError
multi images bit length error
multi_images_bit 长度必须为4
InvalidParameter.MultiImagesBitCharError
multi images bit invalid char error
只能包含 '0' 和 '1'
InvalidParameter.MultiImagesBitMismatch
multi_images_bit_count_mismatch_error
'1' 的数量须匹配图片数
InvalidParameter.MeshFormatNotSupported
mesh format not supported
mesh 仅支持 GLB 格式
InvalidParameter.TextureNotSupported
model does not support texture
v2.0/v2.1 不支持 request_type=2
InternalError
system error
系统内部异常
中国站