文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯混元生3D>快速入门

快速入门

最近更新时间：2025-12-05 10:35:42

我的收藏

本页目录：

操作场景

本文将为您介绍如何使用 API 3.0 Explorer 在线调试腾讯混元生3D 相关接口。

准备工作

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

操作步骤

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

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

2. 获取密钥信息

密钥是指：SecretId 和 SecretKey ，为降低密钥泄漏的风险，自2023年11月30日起，对所有主账号、子账号的密钥，关闭查询 SecretKey 的功能，仅支持在创建时查看，请及时保存 SecretKey 。如果忘记 SecretKey ，可以删除密钥之后重新创建一个。
说明：
子账户调用需要主账户授权才可以使用，主账户登录之后点击用户列表，在对应的子账户后面选择授权，会弹出关联策略的弹窗，输入授权策略名称之后进行搜索，选择对应的策略点击确认。
地址：https://console.cloud.tencent.com/cam
授权策略：QcloudAI3DFullAccess




3. 调用 API 接口（示例）

因为混元生3D 接口是异步接口，需要调用提交混元生3D 专业版任务跟查询混元生3D 专业版任务2个接口。
接口
说明
提交混元生3D 专业版任务
输入 Prompt 或者图片之后提交请求，请求成功会返回一个 JobId。
查询混元生3D 专业版任务
通过提交混元生3D 专业版任务返回的 JobId 去查询结果信息。
任务状态说明：
WAIT ：等待中。
RUN ：执行中。
FAIL ：任务失败。
DONE ：任务成功。
QueryHunyuanTo3DProJob 接口提交查询的时候会返回 Status（任务状态），当 Status 为 FAIL 或者 DONE 的时候，表示任务已经处理完成。
如果 Status 为 DONE ：可以通过返回的 ResultFile3Ds 参数获取到结果文件。
如果 Status 为 FAIL ：可以通过返回的 ErrorCode 参数跟 ErrorMessage 参数获取报错原因。
如果 Status 为 WAIT 或者 RUN ：则表示没有拉取到结果信息，需要继续拉取。

方式一：通过 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 CommonClient
from tencentcloud.common import credential
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
import time
import os



SecretId = ""   # 密钥的SecretId
SecretKey = ""  # 密钥的SecretKey
host = "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 os
import json
import types
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.ai3d.v20250513 import ai3d_client, models
import time



SecretId = ""   # 密钥的SecretId
SecretKey = ""  # 密钥的SecretKey
host = "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, err


def 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)


中国站
目录