大模型服务平台 TokenHub Hi3D 调用指南

一、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 任务