帮你快速理解、总结文档立即下载
文档中心>大模型服务平台 TokenHub>调用指南>3D 生成模型>混元调用指南

混元调用指南

最近更新时间：2026-08-19 15:55:00
我的收藏

本页目录：

概述

腾讯混元生3D（Tencent HY 3D）​​ 基于腾讯自研生成式 AI 大模型，提供3D 内容生成的 API 技术服务。API 支持通过文本描述或上传2D 图像自动创建高精度3D 模型，可广泛应用于3D 打印、家装家具、产品设计等领域。混元生3D API 显著降低了专业级建模的技术门槛，提升了创作效率及设计灵活性，赋能多行业高效完成3D 内容生产。

立即使用

大模型服务平台 TokenHub 采用标准 OpenAI Chat Completions API 协议，您可以直接使用 OpenAI SDK 或任何兼容客户端接入。您可以调用 API 对腾讯混元生3D 模型进行操作，具体使用方式详见对应接口文档。
模型
Model name
接口功能
HY-3D-3.0
hy-3d-3.0
生成更高精度以及更高质量的3D 模型，支持文生3D、图生3D、多视图生3D、单几何生成（白模）、草图生3D、智能拓扑生3D 功能。
HY-3D-3.1
hy-3d-3.1
3.1 版本模型在几何、纹理质量上实现进一步提升，支持八视图多角度输入、文生3D、图生3D、单几何生成（白模）功能。
HY-3D-Express
可在较短时间内生成3D 模型文件。
HY-3D-Component
输入3D 模型后，可自动识别模型结构，生成对应模型的3D 组件。
HY-3D-Format
输入3D 模型文件后，可进行3D 模型文件格式转换。
HY-3D-Motion
输入文本后，可根据文本描述生成对应的 3D 人物动作数据，输出带动画数据的 FBX 文件。
HY-3D-Retopology
采用 Polygon 1.5模型，输入3D 高模后，可生成布线规整，较低面数的3D 模型。
HY-3D-Rigging
3D 模型绑骨蒙皮接口，基于混元大模型，根据输入的人物或动物模型进行绑骨蒙皮，输出带骨骼信息的3D 模型。
HY-3D-Texture
输入单几何模型和参考图或文字描述后，可生成对应的纹理贴图。
HY-3D-UV
hy-3d-uv
输入3D 模型后，可自动化生成高质量 UV 切线模型。

图片输入要求

文件大小不应超过 10MB（经编码后大小会增加约 30%，建议实际输入的图片文件大小不超过 8MB），分辨率最低128x128，最高5000x5000。
输入图片建议：
1. 背景简洁（纯色背景）；
2. 不含文字或渐变色；
3. 仅包含单一主体；
4. 主体在画面中占比超过 50%。


OpenAI 兼容接口调用示例

混元生3D API 兼容了 OpenAI 的接口规范，这意味着您可以在 OpenAI 协议中使用 cURL 来调用混元生3D 大模型。您仅需要将 YOUR_API_KEY 替换成混元的相关配置，即可将您的应用切换到混元生3D。

提交混元生3D 任务

base_url：https://tokenhub.tencentmaas.com/v1/api/3d/submit。
请求示例代码如下，其中：HY-3D-3.0、HY-3D-3.1请求的具体参数与 提交混元生3D 专业版任务 接口一致；HY-3D-Express 请求的具体参数与 提交混元生3D 极速版任务 接口一致。但参数统一以小写下划线形式呈现，如 ResultFormat 需要写为 result_format。
以下以 HY-3D-3.0模型为例：
cURL
curl --location 'https://tokenhub.tencentmaas.com/v1/api/3d/submit' \\
--header 'Authorization: Bearer YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--data '{
    "model": "hy-3d-3.0",
    "prompt": "一只小狗"
}'
响应示例代码如下，请记录响应 id ，作为查询混元生3D 任务的输入参数：
cURL
{
    "id": "14*******984",
    "request_id": "75********33",
    "object": "3d_job",
    "created_at": 1774806931,
    "status": "queued"
}

查询混元生3D 任务

base_url：https://tokenhub.tencentmaas.com/v1/api/3d/query。
请求示例代码如下，其中：id 为提交混元生3D 任务时响应代码中的 id ；HY-3D-3.0、HY-3D-3.1请求的具体参数与 查询混元生3D 专业版任务 接口一致；HY-3D-Express 请求的具体参数与 查询混元生3D 极速版任务 接口一致。但参数统一以小写下划线形式呈现，如 ResultFormat 需要写为 result_format。
以下以 HY-3D-3.0模型为例：
cURL
curl --location 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\
--header 'Authorization: Bearer YOUR_API_KEY' \\
--header 'Content-Type: application/json' \\
--data '{
    "model": "hy-3d-3.0",
    "id": "1429890795996585984"
}'
响应（生成中）：
cURL
{
    "request_id": "c41*******bf",
    "object": "3d_job",
    "created_at": 1774806968,
    "status": "in_progress"
}
响应（已完成）：
cURL
{
    "request_id": "7824******50",
    "object": "3d_job",
    "created_at": 1774807344,
    "completed_at": 1774807344,
    "status": "completed",
    "data": [
        {
            "type": "obj",
            "url": "https://hunyuan-test*******552a3",
            "preview_image_url": "https://hunyuan-test*******125a56c0081cc404"
        },
        {
            "type": "glb",
            "url": "https://hunyuan*****-b668642f9ae",
            "preview_image_url": "https://hunyuan****1deca56c0081cc404"
        }
    ]
}

中国站