帮你快速理解、总结文档立即下载
文档中心>媒体处理>API 文档>AIGC场景应用相关接口>查询混元3D任务结果

查询混元3D任务结果

最近更新时间：2026-10-09 02:40:11
我的收藏

本页目录：

1. 接口描述

接口请求域名： mps.tencentcloudapi.com 。

查询混元3D任务对应的结果

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：QueryHunyuan3DTask。
Version 是 String 公共参数，本接口取值：2019-06-12。
Region 否 String 公共参数，本接口不需要传递此参数。
TaskId 否 String

任务ID


示例值：4deda860-a9a0-47e3-81f1-00cadf02a44c

3. 输出参数

参数名称 类型 描述
Status String

任务状态

枚举值：

  • WAIT： 已排队，等待执行
  • RUN： 正在执行
  • DONE： 已成功完成，ResultFile3Ds 有值
  • FAIL： 已失败，ErrorCode / ErrorMessage 有值

示例值：DONE
Progress Integer

进度百分比，0~100。未知时为 0；DONE 时应为 100；FAIL 时保留最后一次已知值


示例值：100
ErrorCode String

仅 Status=FAIL 时有值，字符串错误码（如 InternalError.ModelInference）


示例值：ResourceNotFound.TaskId
ErrorMessage String

仅 Status=FAIL 时有值，详细文案


示例值：task not found or expired
ResultFile3Ds Array of File3D

仅 Status=DONE 时有值，产物文件列表
TaskId String

任务ID


示例值：r_75466f84b0b911f1b1b66aacb78dd458
TaskType String

任务类型

枚举值：

  • text_to_3d： 文生3D
  • image_to_3d： 图生3D
  • multiview_to_3d： 多视图生3D
  • mesh_to_texture： 网格生纹理
  • mesh_to_geometry： 网格生几何

示例值：text_to_3d
Prompt String

输入的Prompt


示例值：a cute chicken, cartoon style
RefImage String

图生3D场景下输入的图片URL


示例值：https://hunyuan-base-test-1258344703.cos.ap-guangzhou.myqcloud.com/public/test/eba3542f-5e19-4862-b95d-c2d28e7ef91e-latent.png
MultiViewImages Array of ViewImage

多图生3D场景下输入的图片信息
CreateTime Timestamp ISO8601

任务创建时间


示例值：2026-09-15T03:56:40Z
UpdateTime Timestamp ISO8601

任务更新时间


示例值：2026-09-15T04:00:14Z
FaceCount Integer

提交任务的目标面数


示例值：500000
GenerateType String

生成类型

枚举值：

  • Normal： 生成完整 3D 资产（几何 + 纹理）
  • Geometry： 只生成几何体（无纹理，输出速度更快）
  • Texture： 只生成纹理（需要传 MeshUrl）

默认值：Normal


示例值：Normal
QueuePosition Integer

任务在队列中的位置，数值越小越靠前；


示例值：2
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 任务不存在

输入示例

POST / HTTP/1.1
Host: mps.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: QueryHunyuan3DTask
<公共请求参数>

{
    "TaskId": "4deda860-a9a0-47e3-81f1-00cadf02a44c"
}

输出示例

{
    "Response": {
        "ErrorCode": "ResourceNotFound.TaskId",
        "ErrorMessage": "task not found or expired",
        "RequestId": "cec25a1e-0875-44f0-87da-2a1ebabee48b"
    }
}

示例2 回包较为完整的示例

输入示例

POST / HTTP/1.1
Host: mps.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: QueryHunyuan3DTask
<公共请求参数>

{
    "TaskId": "r_75466f84b0b911f1b1b66aacb78dd458"
}

输出示例

{
    "Response": {
        "CreateTime": "2026-09-15T03:56:40Z",
        "FaceCount": 500000,
        "Progress": 100,
        "Prompt": "a cute chicken, cartoon style",
        "ResultFile3Ds": [
            {
                "PreviewImageUrl": "https://hunyuan-base-prod-1258344703.cos.ap-guangzhou.myqcloud.com/openapi/text2img/838676194d9cada36394b6ef08ee9bac.png?q-ak=************************************&q-header-list=&q-key-time=1789444785%3B1789531185&q-sign-algorithm=sha1&q-sign-time=1789444785%3B1789531185&q-signature=1559acdb874c9459b83599b5b6cae25f13f0dabd&q-url-param-list=",
                "Type": "GLB",
                "Url": "https://hunyuan-3d-1258344703.cos.ap-guangzhou.myqcloud.com/gen_tmp_test/efcec080d3e049c3911d5781518e59e7/946764dab065116e55f6204f00e43eab.glb?q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1789444780%3B1789531180&q-key-time=1789444780%3B1789531180&q-header-list=&q-url-param-list=&q-signature=cbc0494a4e5504a41d53698f2916ca8845a3e9f9"
            }
        ],
        "Status": "DONE",
        "TaskId": "r_75466f84b0b911f1b1b66aacb78dd458",
        "TaskType": "text_to_3d",
        "UpdateTime": "2026-09-15T04:00:14Z",
        "RequestId": "531aa6de-1144-4797-9b87-b8c79c998160"
    }
}

示例3 返回RefImage

输入示例

POST / HTTP/1.1
Host: mps.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: QueryHunyuan3DTask
<公共请求参数>

{
    "TaskId": "r_e6fb6e39b0ba11f1b1b66aacb78dd458"
}

输出示例

{
    "Response": {
        "CreateTime": "2026-09-15T04:07:01Z",
        "FaceCount": 500000,
        "Progress": 0,
        "RefImage": "https://hunyuan-base-test-1258344703.cos.ap-guangzhou.myqcloud.com/public/test/eba3542f-5e19-4862-b95d-c2d28e7ef91e-latent.png",
        "Status": "RUN",
        "TaskId": "r_e6fb6e39b0ba11f1b1b66aacb78dd458",
        "TaskType": "image_to_3d",
        "UpdateTime": "2026-09-15T04:07:18Z",
        "RequestId": "7b545f16-7552-4cc9-acfc-04cdc60581e8"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

该接口暂无业务逻辑相关的错误码，其他错误码详见 公共错误码。

中国站