腾讯混元生3D 快速入门

一、准备工作

在使用腾讯混元生3D 服务前，你需要先注册腾讯云账号。如果没有账号，请参考 注册腾讯云 教程。

二、1. 开通腾讯混元生3D 服务

注册并通过实名认证后，登录 腾讯混元生3D 控制台，阅读和同意相关服务协议，并单击开通，即可开通服务。

三、2. 获取密钥信息

密钥是指：SecretId 和 SecretKey ，为降低密钥泄漏的风险，自2023年11月30日起，对所有主账号、子账号的密钥，关闭查询 SecretKey 的功能，仅支持在创建时查看，请及时保存 SecretKey 。如果忘记 SecretKey ，可以删除密钥之后重新创建一个。

注意：说明：

四、3. 调用 API 接口（示例）

因为混元生3D 接口是异步接口，需要调用提交混元生3D 专业版任务跟查询混元生3D 专业版任务2个接口。

五、方式一：通过 API Explorer 在线调用接口

调用提交混元生3D 专业版任务接口：输入参数之后点击发起调用，会返回提交混元生3D 专业版任务的结果信息。

注意：说明：

注意：对应参数说明可前往 API 接口文档 查看。

成功结果参考：请求成功会返回 JobId 跟 RequestId 。

失败结果参考：请求失败会返回失败的 Code 和 Message 。

{ "Response": { "Error": { "Code": "FailedOperation.DownloadError", "Message": "文件下载失败。" }, "RequestId": "da95773b-b659-4555-b94e-c6000c283730" }}

调用查询混元生3D 专业版任务接口：通过提交混元生3D 专业版任务成功的 JobId 获取结果信息。

任务状态说明：

·WAIT ：等待中。

·RUN ：执行中。

·FAIL ：任务失败。

·DONE ：任务成功。

提交查询的时候会返回 Status（任务状态），当 Status 为 DONE 、FAIL 的时候，表示任务已经处理完成。

·如果 Status 为 DONE ：可以通过返回的 ResultFile3Ds 参数获取到结果信息。

·如果 Status 为 FAIL ：可以通过返回的 ErrorCode 参数跟 ErrorMessage 参数获取报错原因。

·如果 Status 为 WAIT 或者 RUN ：则表示没有拉取到结果信息，需要继续拉取。

返回成功结果：

{ "Response": { "ErrorCode": "", "ErrorMessage": "", "RequestId": "626734da-d939-4a81-bea5-7df7bc4a0f43", "ResultFile3Ds": [ { "PreviewImageUrl": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/***/preview_525ba498-c8d9-40eb-a33c-62b979cd21ca_0.png?***e827ab0aa9cdf", "Type": "OBJ", "Url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/***/525ba498-c8d9-40eb-a33c-62b979cd21ca_0.zip?***b7b87570" }, { "PreviewImageUrl": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/***/preview_525ba498-c8d9-40eb-a33c-62b979cd21ca_0.png?***27ab0aa9cdf", "Type": "GLB", "Url": "https://hunyuan-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/3d/output/**/525ba498-c8d9-40eb-a33c-62b979cd21ca_0.glb?q-sign-algorithm=***aa2e7c0bb967512d5" } ], "Status": "DONE" }}

六、方式二：安装 SDK 调用接口

前往 API Explorer 点击代码示例，可以查询到目前可以安装 SDK 的开发语言，选择安装对应版本的 SDK 进行调用：

以下为：python语言的 SDK 调用方式示例：

·接入方式：SDK Common Client

from tencentcloud.common.common_client import CommonClientfrom tencentcloud.common import credentialfrom tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKExceptionfrom tencentcloud.common.profile.client_profile import ClientProfilefrom tencentcloud.common.profile.http_profile import HttpProfileimport timeimport osSecretId = "" # 密钥的SecretIdSecretKey = "" # 密钥的SecretKeyhost = "ai3d.tencentcloudapi.com" # 接口请求域名Version = "2025-05-13" # Version，接口固定值，按api文档要求填写Region = "ap-guangzhou" # 地域，按api文档要求填写module = host.split('.', 1)[0]# 使用common 方式调用def api(SecretId,SecretKey,host,Action,Version,Region,module,params): try: # 实例化一个认证对象，入参需要传入腾讯云账户 SecretId 和 SecretKey，此处还需注意密钥对的保密 # 代码泄露可能会导致 SecretId 和 SecretKey 泄露，并威胁账号下所有资源的安全性。以下代码示例仅供参考，建议采用更安全的方式来使用密钥，请参见：https://cloud.tencent.com/document/product/1278/85305 # 密钥可前往页面控制台 https://console.cloud.tencent.com/cam/capi 进行获取 cred = credential.Credential(SecretId, SecretKey) httpProfile = HttpProfile() # 域名首段必须和下文中CommonClient初始化的产品名严格匹配 httpProfile.endpoint = host clientProfile = ClientProfile() clientProfile.httpProfile = httpProfile # common client方法支持指定header，如 X-TC-TraceId、X-TC-Canary headers = {} # 实例化要请求的common client对象，clientProfile是可选的。 版本 common_client = CommonClient(module, Version, cred, Region, profile=clientProfile) # 接口参数作为json字典传入，得到的输出也是json字典，请求失败将抛出异常，headers为可选参数 resp = common_client.call_json(Action, params, headers=headers) code = 0 return code,resp except TencentCloudSDKException as err: return err.code,err# 提交混元生3D专业版任务接口Action = "SubmitHunyuanTo3DProJob"# 提交混元生3D专业版任务接口的请求参数Submit_params = { "Prompt": "熊猫"}# 接口成功状态success = ["DONE"]# 失败状态fail = ["FAIL"]# 运行中的状态run = ["WAIT", "RUN"]# 提交混元生3D专业版任务请求sub_code,sub_resp = api(SecretId,SecretKey,host,Action,Version,Region,module,Submit_params)# 打印请求结果print(sub_resp)# 判断请求状态是否成功，当状态为0表示成功if sub_code == 0: # 等待10s time.sleep(60) # 获取返回的jobid，提交查询混元生3D专业版任务 JobId = sub_resp["Response"]["JobId"] # 查询混元生3D专业版任务接口的请求参数 query_params = {"JobId": JobId} # 查询混元生3D专业版任务接口 Action = "QueryHunyuanTo3DProJob" # 查询混元生3D专业版任务请求 qu_code, qu_resp = api(SecretId, SecretKey, host, Action, Version, Region, module, query_params) # 判断请求状态是否成功，当状态为0表示成功 if qu_code == 0: while True: # 获取查询混元生3D专业版任务的任务状态码 Status = qu_resp["Response"]["Status"] # 判断任务状态 if Status in success: # 如果成功返回结果信息 print(qu_resp) break elif Status in fail: # 如果失败打印结果信息 print(qu_resp) break elif Status in run: # 当状态为运行中等状态的时候，等待5s再查询结果信息 time.sleep(3) qu_code, qu_resp = api(SecretId, SecretKey, host, Action, Version, Region, module, query_params) else: # 打印报错信息 print(qu_resp)else: # 打印报错信息 print(sub_resp)

·接入方式：SDK

# -*- coding: utf-8 -*-import osimport jsonimport typesfrom tencentcloud.common import credentialfrom tencentcloud.common.profile.client_profile import ClientProfilefrom tencentcloud.common.profile.http_profile import HttpProfilefrom tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKExceptionfrom tencentcloud.ai3d.v20250513 import ai3d_client, modelsimport timeSecretId = "" # 密钥的SecretIdSecretKey = "" # 密钥的SecretKeyhost = "ai3d.tencentcloudapi.com" # 接口请求域名Region = "ap-guangzhou" # 地域，按api文档要求填写# 使用common 方式调用def SubmitHunyuanTo3DProJob(params): try: # 密钥信息从环境变量读取，需要提前在环境变量中设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY # 使用环境变量方式可以避免密钥硬编码在代码中，提高安全性 # 生产环境建议使用更安全的密钥管理方案，如密钥管理系统(KMS)、容器密钥注入等 # 请参见：https://cloud.tencent.com/document/product/1278/85305 # 密钥可前往页面控制台 https://console.cloud.tencent.com/cam/capi 进行获取 # cred = credential.Credential(os.getenv("TENCENTCLOUD_SECRET_ID"), os.getenv("TENCENTCLOUD_SECRET_KEY")) # 使用临时密钥示例 cred = credential.Credential(SecretId, SecretKey) # 实例化一个http选项，可选的，没有特殊需求可以跳过 httpProfile = HttpProfile() httpProfile.endpoint = "ai3d.tencentcloudapi.com" # 实例化一个client选项，可选的，没有特殊需求可以跳过 clientProfile = ClientProfile() clientProfile.httpProfile = httpProfile # 实例化要请求产品的client对象,clientProfile是可选的 client = ai3d_client.Ai3dClient(cred, "ap-guangzhou", clientProfile) # 实例化一个请求对象,每个接口都会对应一个request对象 req = models.SubmitHunyuanTo3DProJobRequest() req.from_json_string(json.dumps(params)) # 返回的resp是一个SubmitHunyuanTo3DProJobResponse的实例，与请求对象对应 resp = client.SubmitHunyuanTo3DProJob(req) # 输出json格式的字符串回包 print(resp.to_json_string()) code = 0 return code, resp except TencentCloudSDKException as err: print(err) return err.code, errdef QueryHunyuanTo3DProJob(params): try: # 密钥信息从环境变量读取，需要提前在环境变量中设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY # 使用环境变量方式可以避免密钥硬编码在代码中，提高安全性 # 生产环境建议使用更安全的密钥管理方案，如密钥管理系统(KMS)、容器密钥注入等 # 请参见：https://cloud.tencent.com/document/product/1278/85305 # 密钥可前往页面控制台 https://console.cloud.tencent.com/cam/capi 进行获取 # cred = credential.Credential(os.getenv("TENCENTCLOUD_SECRET_ID"), os.getenv("TENCENTCLOUD_SECRET_KEY")) # 使用临时密钥示例 cred = credential.Credential(SecretId, SecretKey) # 实例化一个http选项，可选的，没有特殊需求可以跳过 httpProfile = HttpProfile() httpProfile.endpoint = "ai3d.tencentcloudapi.com" # 实例化一个client选项，可选的，没有特殊需求可以跳过 clientProfile = ClientProfile() clientProfile.httpProfile = httpProfile # 实例化要请求产品的client对象,clientProfile是可选的 client = ai3d_client.Ai3dClient(cred, "ap-guangzhou", clientProfile) # 实例化一个请求对象,每个接口都会对应一个request对象 req = models.QueryHunyuanTo3DProJobRequest() req.from_json_string(json.dumps(params)) # 返回的resp是一个QueryHunyuanTo3DProJobResponse的实例，与请求对象对应 resp = client.QueryHunyuanTo3DProJob(req) # 输出json格式的字符串回包 print(resp.to_json_string()) code = 0 return code, resp except TencentCloudSDKException as err: print(err) return err.code, err# 提交混元生3D专业版任务接口的请求参数Submit_params = { "Prompt": "熊猫"}# 接口成功状态success = ["DONE"]# 失败状态fail = ["FAIL"]# 运行中的状态run = ["WAIT", "RUN"]# 提交混元生3D专业版任务请求sub_code,sub_resp = SubmitHunyuanTo3DProJob(Submit_params)# 打印请求结果print(sub_resp)# 判断请求状态是否成功，当状态为0表示成功if sub_code == 0: # 等待10s time.sleep(10) # 获取返回的jobid，提交查询混元生3D专业版任务 JobId = sub_resp.JobId # 查询混元生3D专业版任务接口的请求参数 query_params = {"JobId": JobId} # 查询混元生3D专业版任务请求 qu_code, qu_resp = QueryHunyuanTo3DProJob(query_params) # 判断请求状态是否成功，当状态为0表示成功 if qu_code == 0: while True: # 获取查询混元生3D专业版任务的任务状态码 Status = qu_resp.Status # 判断任务状态 if Status in success: # 如果成功返回结果信息 print(qu_resp) break elif Status in fail: # 如果失败打印结果信息 print(qu_resp) break elif Status in run: # 当状态为运行中等状态的时候，等待5s再查询结果信息 time.sleep(1) qu_code, qu_resp = QueryHunyuanTo3DProJob(query_params) else: print(qu_resp) break else: # 打印报错信息 print(qu_resp)else: # 打印报错信息 print(sub_resp)