混元生3D API批量调用与SDK代码示例

原创

hollyx

发布于 2026-10-29 15:40:54

690

想把 AI 3D 生成接入自己的批量生产管线，需要解决两件事：异步任务的提交和轮询、并发控制。混元生3D 是异步接口——提交任务拿到 JobId，轮询查询直到 DONE。本文给出 Python 完整示例和批量调用要点。

一、接口调用流程

混元生3D 接口是异步的，不能一次调用直接取结果。流程：

开始
  ↓
调用 SubmitHunyuanTo3DProJob → 返回 JobId
  ↓
调用 QueryHunyuanTo3DProJob（用 JobId 查询）
  ↓
检查 Status：WAIT/RUN → 等待再查
              FAIL → 错误处理
              DONE → 从 ResultFile3Ds 取文件
  ↓
结束

接口请求域名为 ai3d.tencentcloudapi.com，版本号 2025-05-13，地域 ap-guangzhou。

二、Python SDK 完整示例

安装 SDK

pip install tencentcloud-sdk-python

单次生成示例

import json
import time
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.ai3d.v20250513 import ai3d_client, models

# 密钥信息
SecretId = ""       # 替换为你的 SecretId
SecretKey = ""      # 替换为你的 SecretKey
Region = "ap-guangzhou"

def submit_job(params):
    """提交混元生3D专业版任务"""
    cred = credential.Credential(SecretId, SecretKey)
    httpProfile = HttpProfile()
    httpProfile.endpoint = "ai3d.tencentcloudapi.com"
    clientProfile = ClientProfile()
    clientProfile.httpProfile = httpProfile
    client = ai3d_client.Ai3dClient(cred, Region, clientProfile)

    req = models.SubmitHunyuanTo3DProJobRequest()
    req.from_json_string(json.dumps(params))
    resp = client.SubmitHunyuanTo3DProJob(req)
    return resp

def query_job(job_id):
    """查询混元生3D专业版任务结果"""
    cred = credential.Credential(SecretId, SecretKey)
    httpProfile = HttpProfile()
    httpProfile.endpoint = "ai3d.tencentcloudapi.com"
    clientProfile = ClientProfile()
    clientProfile.httpProfile = httpProfile
    client = ai3d_client.Ai3dClient(cred, Region, clientProfile)

    req = models.QueryHunyuanTo3DProJobRequest()
    req.from_json_string(json.dumps({"JobId": job_id}))
    resp = client.QueryHunyuanTo3DProJob(req)
    return resp

# 提交任务
submit_params = {"Prompt": "一只熊猫"}
sub_resp = submit_job(submit_params)
job_id = sub_resp.JobId

# 轮询结果
while True:
    query_resp = query_job(job_id)
    status = query_resp.Status
    if status == "DONE":
        # 从 ResultFile3Ds 获取文件
        for f in query_resp.ResultFile3Ds:
            print(f"格式: {f.Type}, URL: {f.Url}")
        break
    elif status == "FAIL":
        print(f"生成失败: {query_resp.ErrorCode} - {query_resp.ErrorMessage}")
        break
    else:  # WAIT, RUN
        time.sleep(5)

批量生成示例

专业版默认3个并发。在没有购买并发叠加包的情况下，批量生成需要自己做队列控制：

import json
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.ai3d.v20250513 import ai3d_client, models

SecretId = ""
SecretKey = ""
Region = "ap-guangzhou"

def generate_single(client, prompt):
    """提交 + 轮询单个生成任务"""
    submit_req = models.SubmitHunyuanTo3DProJobRequest()
    submit_req.from_json_string(json.dumps({"Prompt": prompt}))
    sub_resp = client.SubmitHunyuanTo3DProJob(submit_req)
    job_id = sub_resp.JobId

    while True:
        query_req = models.QueryHunyuanTo3DProJobRequest()
        query_req.from_json_string(json.dumps({"JobId": job_id}))
        query_resp = client.QueryHunyuanTo3DProJob(query_req)

        if query_resp.Status == "DONE":
            return {"prompt": prompt, "status": "DONE",
                    "files": [{"type": f.Type, "url": f.Url}
                              for f in query_resp.ResultFile3Ds]}
        elif query_resp.Status == "FAIL":
            return {"prompt": prompt, "status": "FAIL",
                    "error": query_resp.ErrorMessage}
        else:
            time.sleep(5)

# 初始化client
cred = credential.Credential(SecretId, SecretKey)
httpProfile = HttpProfile()
httpProfile.endpoint = "ai3d.tencentcloudapi.com"
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = ai3d_client.Ai3dClient(cred, Region, clientProfile)

# 批量prompts
prompts = [
    "一只熊猫",
    "一把锈迹斑斑的铁剑",
    "一个木质酒桶",
    "一个水晶球",
    "一个面包",
]

# 专业版3并发，用线程池模拟
results = []
with ThreadPoolExecutor(max_workers=3) as executor:
    futures = {executor.submit(generate_single, client, p): p for p in prompts}
    for future in as_completed(futures):
        result = future.result()
        results.append(result)
        print(f"完成: {result['prompt']} -> {result['status']}")

print(f"\n批量完成: {len(results)}/{len(prompts)}")

文生3D 后做格式转换（电商场景）

# Step1: 生成模型
submit_params = {
    "Prompt": "一台银色咖啡机",
    "GenerateType": "Normal"  # 20积分
}
sub_resp = submit_job(submit_params)
# ... 轮询拿到glb文件URL ...

# Step2: 转GIF做商品预览
convert_req = models.Convert3DFormatRequest()
convert_req.from_json_string(json.dumps({
    "File3D": glb_url,
    "Format": "GIF"  # 5积分
}))
convert_resp = client.Convert3DFormat(convert_req)
print(f"预览GIF: {convert_resp.ResultFile3D}")

三、接口说明与参数

提交接口 SubmitHunyuanTo3DProJob

参数	必选	说明
Prompt	否（与ImageUrl二选一）	文本描述
ImageUrl/ImageBase64	否	图片URL或Base64
GenerateType	否（默认Normal）	Normal/LowPoly/Geometry/Sketch
EnablePBR	否（附加+10积分）	生成PBR材质
FaceCount	否（附加+10积分）	自定义面数
ResultFormat	否（附加+5积分）	指定输出格式

任务状态：WAIT（等待中）/ RUN（执行中）/ FAIL（失败）/ DONE（成功）

四、批量调用要点

并发控制

能力	说明
默认并发	专业版3个，极速版和其他接口1个
提升方式	购买并发叠加包（3万元/并发/月）
线程池	max_workers 需 <= 当前并发限制

积分预算管理

提前算总积分预算：

total_credits = 0
for item in batch:
    credits = 20  # Normal 基础
    if item.get("enable_pbr"):
        credits += 10
    if item.get("face_count"):
        credits += 10
    total_credits += credits

print(f"预计消耗: {total_credits}积分 (预付费{total_credits * 0.1}元)")

失败重试

生成失败的任务不扣积分。可以直接重试，不需要额外预算：

for attempt in range(3):
    result = generate_single(client, prompt)
    if result["status"] == "DONE":
        break
    time.sleep(10)

在线调试

如果不想先写代码，可以使用 API Explorer 在线调试接口，提交参数后直接看到返回的 JobId 和后续轮询结果。

小结

混元生3D 是异步接口，批量调用的核心是"提交-轮询-队列控制"。Python SDK 支持完整的异步调用循环，用 ThreadPoolExecutor 限制并发数即可满足批量产出需求。关键参数：专业版默认3并发、失败不扣积分可重试、积分预算提前算。

参考来源：腾讯混元生3D 快速入门、API 概览、模型格式转换

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

并发