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

Hi3D 调用指南

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

本页目录：

简介

hi3d 模型，根据输入的图片智能生成3d。本文档适用范围：hi3d-2.1、hi3d-3.0。

对接说明

1. 获取 API Key

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

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

2. 并发额度

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

接口文档

提交 hi3d 任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
模型版本。可选 hi3d-2.1、hi3d-3.0；示例值：hi3d-3.0。
request_type
否
int
请求类型：1=仅生成几何，2=基于已有几何生成纹理，3=同时生成几何与纹理。默认 3。request_type=2 仅 hi3d-3.0 支持。
images
否
string
单图 URL。与 image_url、image_base64、multi_images 四选一。
image_url
否
string
单图 URL。与 images、image_base64、multi_images 四选一。
image_base64
否
string
单图 Base64 编码。与 images、image_url、multi_images 四选一。
multi_images
否
string[]
多视图 URL 列表，最多 4 张（前、后、左、右视图），与单图参数互斥。
multi_images_bit
否
string
多视图位图，长度必须为 4 且仅含 0 或 1；1 的数量必须与 multi_images 数量一致，例如 1010 表示前视图和左视图。
resolution
否
string
分辨率。hi3d-2.1 可选 1536fast、1536pro，默认 1536pro；hi3d-3.0 可选 2048quality、2048master，默认 2048quality。
pbr
否
int
PBR 开关：1=开启（默认），0=关闭。
shading
否
float
去光影程度，范围 0.0～1.0，默认 0.5。
face
否
int
模型面数。hi3d-2.1 范围 100000～2000000；hi3d-3.0 范围 100000～5000000。
format
否
int
输出格式：1=obj（默认），2=glb，3=stl，4=fbx，5=usdz，6=3mf。
mesh_url
否
string
GLB 格式几何模型 URL。request_type=2 时必填，且必须以 http:// 或 https:// 开头；仅 hi3d-3.0 支持。
callback_url
否
string
任务完成或失败时接收通知的回调地址，必须以 http:// 或 https:// 开头。
输出参数
参数名称
类型
描述
id
string
任务 ID，用于查询任务。
object
string
返回对象类型，固定为 3d_job。
status
string
任务初始状态，通常为 queued。
created_at
int
任务创建时间戳，单位为秒。
request_id
string
请求 ID，用于问题定位。
error
object
错误信息，仅任务失败时返回。
error.code
string
错误码。
error.message
string
错误信息。
error.type
string
错误类型，固定为 api_error。

查询 hi3d 任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
模型版本，必须与提交任务时一致，可选 hi3d-2.1、hi3d-3.0。
id
是
string
任务 ID，由提交任务接口返回。
输出参数
参数名称
类型
描述
status
string
任务状态：queued=排队中、processing=处理中、completed=完成、failed=失败。
data.url
string
生成物下载 URL，仅任务完成时返回，有效期 1 小时。
data.cover_url
string
生成物封面图 URL，仅任务完成时返回，有效期 1 小时。
result_credit_consumed
int
本次任务实际消耗的积分总量，仅任务完成时返回。
result_credit_details
string
本次任务积分消耗明细，JSON 字符串格式；mesh、texture、pbr 分别表示几何、纹理和 PBR 材质积分。
request_id
string
请求 ID，用于问题定位。
created_at
int
任务创建时间戳，单位为秒。
completed_at
int
任务完成时间戳，单位为秒，仅任务完成时返回。
object
string
返回对象类型，固定为 3d_job。
error
object
错误信息，仅任务失败时返回。
error.code
string
错误码。
error.message
string
错误信息。
error.type
string
错误类型，固定为 api_error。

示例

提交 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-3.0"
}'
输出示例
{
  "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-3.0",
  "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"
}

错误码

错误码
HTTP 状态码
说明
1001
400
请求参数无效：请求体 JSON 解析失败、model 为空，或 model 不在支持列表中。
1002
400
查询参数缺失：id 或 model 为空。
FailedOperation.JobNotExist
200
查询的任务 ID 无效或已过期。
FailedOperation.GenerateFailed
200
生成失败（超时或模型无法解析），所耗积分已退还。
FailedOperation.BalanceNotEnough
200
积分余额不足。
InvalidParameter.FileSizeExceedsLimit
200
文件超过 20MB。
InvalidParameter.FaceNotValid
200
面数不合理：hi3d-2.1 为 100000～2000000，hi3d-3.0 为 100000～5000000。
InvalidParameter.ResolutionNotValid
200
分辨率不合理：hi3d-2.1 支持 1536fast、1536pro，hi3d-3.0 支持 2048quality、2048master。
InvalidParameter.RequestTypeNotSupport
200
请求类型不支持。
InvalidParameter.ImageFormatError
200
图片格式错误，仅支持 png、jpeg、jpg、webp。
InvalidParameter.ModelNotSupport
200
模型版本不支持。
InvalidParameter.ImageConflict
200
不能同时上传单图和多视图。
InvalidParameter.ImageRequired
200
必须上传单图或多视图图片。
InvalidParameter.MultiImagesExceedsLimit
200
多视图最多支持 4 张图片。
InvalidParameter.EmptyFile
200
文件不能为空。
InvalidParameter.MeshRequired
200
request_type=2 时必须提供 mesh_url。
InvalidParameter.MeshUrlInvalid
200
mesh_url 必须以 http:// 或 https:// 开头。
InvalidParameter.MultiImagesBitLengthError
200
multi_images_bit 长度必须为 4。
InvalidParameter.MultiImagesBitCharError
200
multi_images_bit 只能包含 0 和 1。
InvalidParameter.MultiImagesBitMismatch
200
multi_images_bit 中 1 的数量必须与 multi_images 图片数量一致。
InvalidParameter.MeshFormatNotSupported
200
mesh_url 仅支持 GLB 格式。
InvalidParameter.TextureNotSupported
200
hi3d-2.1 不支持 request_type=2；该能力仅 hi3d-3.0 支持。
InternalError
200
系统内部异常。

中国站