大模型服务平台 TokenHub HY-3D-Texture 调用指南

一、简介

纹理生成接口，输入单几何模型和参考图后，可生成对应的纹理贴图。

二、1. 获取 API Key

1. 进入 API Key 管理页面，单击创建 API Key。操作详情请参见创建 API Key。

2. 创建完成后，请你务必复制并妥善保管 API Key，在后续配置到工具的流程中将会使用该信息。

注意：说明：

注意：每个账户的密钥都只能当前账户查询，主账户的密钥信息子账户是看不到，子账户如果需要调用接口，需要使用账户自行创建密钥信息。

注意：如果子账户没有办法创建，可能是没有权限创建密钥，需要主账户授权，主账户登录之后点击用户列表，在对应的子账户后面选择授权，会弹出关联策略的弹窗，输入授权策略名称之后搜索，选择对应的策略点击确认。

注意：授权策略：QcloudTokenhubFullAccess

三、2. 并发额度

默认提供1个并发，代表最多能同时处理1个已提交的任务，上一个任务处理完毕后，才能开始处理下一个任务。

并发任务数：表示在调用对应服务的时段内最大可运行的任务数，该任务未完成时，无法提交下一个任务，该任务完成后，可提交下一个任务。

四、提交纹理生成任务

输入参数

参数名称	必选	类型	描述
model	是	string	纹理生成模型名称，默认为 hy-3d-texture。示例值：hy-3d-texture
file_3d	是	object	3d 模型文件。可选值：obj，glb。
multi_view_images	否	array of view_image	多视角的模型图片（仅3.1版本支持），视角参考值：left：左视图right：右视图back：后视图top：顶视图bottom：底视图left_front：左前45°视图right_front：右前45°视图。每个视角仅限制一张图片。图片大小限制：编码后所有图片大小总和不可超过8M。（base64编码下图片大小总和不超过6M，因 base64编码后图片大小会大30%左右）。图片分辨率限制：单边分辨率小于5000且大于128。支持图片格式：支持 jpg 或 png。
image	否	object	3D 模型纹理参考图 base64 数据和参考图 url。base64 和 url 必须提供一个，如果都提供以 url 为准。图片限制：单边分辨率小于4096且大于128，转成 base64 字符串后小于10mb，格式支持 jpg、jpeg、png
enable_pbr	否	boolean	是否开启 pbr 材质生成，默认 false。示例值：false
enable_keep_uv	否	boolean	是否保持模型 uv，开启后模型布线纹理均不改变，uv 布线不跟纹理进行改变，默认 false。示例值：false
texture_size	否	integer	仅支持正方形贴图，分辨率区间为720～4096，默认为4096。示例值：2048

输出参数

参数名称	类型	描述
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

五、查询纹理生成任务

输入参数

参数名称	必选	类型	描述
model	是	string	纹理生成模型名称，默认为 hy-3d-texture。示例值：hy-3d-texture
id	是	string	任务 id。示例值：1357237233311637504

输出参数

参数名称	类型	描述
status	string	completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。示例值：completed
request_id	string	唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
object	string	返回对象类型。3d 任务固定返回 3d_job。
created_at	integer	任务创建时间。
completed_at	integer	任务完成时间。
data	array of object	生成结果列表，包含生成的 3d 模型文件及相关资源信息。详情请参见 data 数据结构。

六、提交纹理生成任务

输入示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/api/3d/submit' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy-3d-texture", "file_3d": { "url": "https://example.com/test.obj" }, "image": { "url": "https://example.com/test.png" }}'

输出示例

{ "id": "14721*****320", "request_id": "11f64379-bb0b-46b2-b89f-17d75fc12365", "object": "3d_job", "created_at": 1784885898, "status": "queued"}

七、查询纹理生成任务

输入示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy-3d-texture", "id": "14721*****320" }'

输出示例

{ "request_id": "74a967e4-0e81-48c1-afde-555b79a1cdf3", "object": "3d_job", "created_at": 1786947866, "completed_at": 1786947866, "status": "completed", "data": [ { "type": "obj", "url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/texture_to_3d/output/1254418******-4b66-bc94-8ad7285e659f.obj" }, { "type": "glb", "url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/texture_to_3d/output/125441*****3-4b66-bc94-8ad7285e659f.glb" }, { "type": "image", "url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/texture_to_3d/output/125441*****d3-4b66-bc94-8ad7285e659f_latent.png" }, { "type": "texture_image", "url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/texture_to_3d/output/1254418****3-4b66-bc94-8ad7285e659f_texture.png" }, { "type": "mtl", "url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/texture_to_3d/output/125441******-4b66-bc94-8ad7285e659f.mtl" } ]}

八、view_image

多视角输入图片对象。

参数名称	必选	类型	描述
view_type	否	string	视角类型。取值：back、left、right 示例值：back
view_image_url	否	string	图片 URL 地址。示例值：https://cos.ap-guangzhou.myqcloud.com/image.jpg
view_image_base64	否	string	图片 Base64 地址。示例值：/9j/4QIQahR0c…N6a2M5ZCI

九、data

生成结果对象。

参数名称	类型	描述
type	string	生成结果文件类型。示例值：obj
url	string	生成结果文件下载地址。