tencent cloud

大模型服务平台 TokenHub

文档大模型服务平台 TokenHub调用指南3D 生成模型Hy 世界模型调用指南

Hy 世界模型调用指南

下载
聚焦模式
字号
最后更新时间： 2026-10-28 16:23:10

概述

混元世界模型是新一代多模态世界模型，致力于打通虚拟与现实的边界。它具备强大的跨模态认知能力，能够将文本描述或图片生成生动、高保真的 3D 场景 或 360° 全景图。
本文介绍如何通过 TokenHub 调用混元 3D 场景模型：Hy-World-2.1-scene，Hy-World-2.1-panorama

前提条件

已 注册腾讯云 账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。
在 控制台-在线推理-视觉模型处开启对应模型的后付费。
说明：
下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

调用流程

两类接口采用不同的调用模式：
接口类型
说明
360° 全景图（同步接口）
单次调用直接返回生成结果，无需轮询。
3D 场景生成（异步接口）
耗时任务（通常 10～20 分钟），分两步调用：
1. 提交任务：调用能力接口（文生场景/图生场景），成功返回任务 id。
2. 轮询结果：携带 id 调用查询任务结果接口，建议每 3~5 秒轮询一次，直至 status = succeeded（生成成功）。
说明：
任务创建成功后请勿重复提交，通过轮询获取结果即可。

模型列表

模型名称
model 参数值
支持能力
模型说明
HY-World-2.1-scene
hy-world2-scene
3D 场景生成
可交互，有空间感的立体3D 场景。
HY-World-2.1-panorama
hy-world2-panorama
360° 全景图生成
可360度环绕查看的场景图片。

3D 场景生成

1. 接口描述

根据文本或图片生成可交互，漫游的实体3D 场景。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/world2-scene

2. 输入参数

参数名
必选
类型
描述
prompt
是
string
文本提示词，描述期望生成的场景内容。取值范围：≤ 600 字符。
image_url
条件必选
string
图片地址，传入公网可访问的图片 URL，分辨率最低要求 512*512，文件大小不超过 10M。
支持格式：JPG、JPEG、PNG、WEBP。
model
条件必选
string
模型版本。取值范围：hy-world2-scene
说明：
3D 场景生成 仅支持文本或图片（二选一）传入，暂不支持文本与图片同时输入。

3. 请求示例

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/world2-scene' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-world2-scene",
  "image_url": "https://example.com/input.jpg"
}'

4. 输出参数

字段
类型
说明
id
string
任务 ID，用于轮询查询任务状态。
request_id
string
唯一请求标识，用于排查问题。

5. 响应示例


{
  "id": "251435731-WandVideo-b917b8211a264cd5a7aa9fb9d836c033",
  "request_id": "02909efb-c5c8-44c6-97ed-bb2ce5e1618d"
}

6. 状态码

任务提交成功后，通过查询任务结果接口轮询，status 字段含义如下：
status
含义
处理建议
queued
排队中
继续轮询。
running
生成中
每 3~5 秒轮询一次，直至 status=succeeded。
succeeded
生成成功
从 data 中获取各格式文件 URL。
failed
生成失败
服务端生成出错，请重试；持续失败请联系技术支持并附任务 id。
cancelled
已取消
任务已取消，需重新发起。
unknown
未知状态
请重试或联系技术支持。

360° 全景图

1. 接口描述

根据文本或图片生成可360度浏览的全景图片。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/world2-panorama

2. 输入参数

参数名
必选
类型
描述
prompt
是
string
文本提示词，描述期望生成的场景内容。取值范围：≤ 600 字符。
images
否
array of string
图片地址列表，传入公网可访问的图片 URL，分辨率最低要求 512*512，文件大小不超过 10M。
支持格式：JPG、JPEG、PNG、WEBP。
model
是
string
模型版本。取值范围：hy-world2-panorama

3. 请求示例

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/world2-panorama' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-world2-panorama",
  "prompt": "现代美术馆室内全景，柔和天光"
}'

4. 输出参数

字段
类型
说明
id
string
本次请求的唯一 ID。
created
integer
请求创建时间（Unix 时间戳）。
status
string
任务状态：succeeded / failed。
data
array
生成结果列表。
data[].cover_image_url
string
封面图 URL，用于快速预览。
data[].super_resolution_image_url
string
超分辨率全景图 URL（主输出）。
request_id
string
唯一请求标识，用于排查问题。
tokenhub_usage
object
用量消耗。
tokenhub_usage.total_tokens
integer
本次任务消耗的 token 数，用于计费/对账。

5. 响应示例


{
    "created": 1787287171,
    "data": [
        {YOUR_SECRET_ID
            "super_resolution_image_url": "https://aigc-output-image-file-1326893053.cos.ap-guangzhou.myqcloud.com/1374200352/1374200352-WandImage-c763284ffc954a999329028a3a8a1013_0.png?q-sign-algorithm=sha1&q-ak=your-secret-id&q-sign-time=1787287164;1787330374&q-key-time=1787287164;1787330374&q-header-list=host&q-url-param-list=&q-signature=da7591e9deb002b9b7360fc8330083f19ea8d6c8"
        }
    ],
    "id": "1374200352-WandImage-c763284ffc954a999329028a3a8a1013",
    "status": "succeeded",
    "version": "1",
    "tokenhub_usage": {
        "total_tokens": 500000
    },
    "request_id": "9d73053a-cb9f-47fe-ab24-fdd2403eb7cf"
}

6. 响应状态码

同步接口直接返回结果，status 字段含义如下：
status
含义
处理建议
succeeded
生成成功
从 data[].super_resolution_image_url 获取全景图。
failed
生成失败
请检查输入参数后重试；持续失败请联系技术支持并附 id。

查询任务结果

1. 接口描述

3D 场景生成为异步接口，任务提交后需轮询该接口获取生成结果。
接口： GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/{task_id}
说明：
路径中的 {task_id} 即提交任务时返回的 id（示例中以 YOUR_TASK_ID 占位）。生成约需 10～20 分钟，建议每 3~5 秒轮询一次。

2. 输入参数

参数名
必选
类型
描述
task_id
是
string
任务 ID（路径参数），即提交任务时返回的 id。

3. 请求示例

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. 输出参数

字段
类型
说明
id
string
本次请求的唯一 ID。
created
integer
请求创建时间（Unix 时间戳）。
status
string
任务状态：queued / running / succeeded / failed / cancelled / unknown。
data
array
生成结果列表（status=succeeded 时有值）。
data[].image_url
string
场景渲染预览图 URL。
data[].scene_url
string
3DGS 场景文件（SPZ 格式）URL。
data[].point_url
string
3D 点云文件（PLY 格式）URL。
data[].mesh_url
string
完整碰撞网格（PLY 格式）URL。
data[].mesh_simplified_url
string
简化碰撞网格（PLY 格式）URL，用于前端实时碰撞检测。
data[].position_info
string
场景空间位置信息 JSON，包含 up_direction、facing_direction、center_point、scale 及边界坐标。
data[].super_resolution_image_url
string
超分辨率渲染图 URL。
request_id
string
唯一请求标识，用于排查问题。
tokenhub_usage
object
用量消耗。
tokenhub_usage.total_tokens
integer
本次任务消耗的 token 数，用于计费/对账。

5. 响应示例

生成成功：

{
  "created": 1787284437,
  "data": [
    {
      "air_wall": {
        "bbox": [
          -46.150852,
          47.925797,
          -6.937543,
          44.305508,
          -25.153587,
          22.927399,
          -0.67803955,
          -3.8229122,
          1.1482356,
          7.252456,
          4.407326,
          1.492669
        ],
        "scene_type": "outdoor"
      },
      "image_url": "https://hunyuan-base-prod-1258344703.cos.ap-guangzhou.myqcloud.com/openapi/text2img/398ddefd8606e2da40d67fd0ba2c0339.png?q-ak\\u003dAKIDRl074nOsGdJ9zjMsCRWP3ShmgS3VtX4S\\u0026q-header-list\\u003d\\u0026q-key-time\\u003d1787283299%3B1787369699\\u0026q-sign-algorithm\\u003dsha1\\u0026q-sign-time\\u003d1787283299%3B1787369699\\u0026q-signature\\u003dcaa743408027047c27f9b58a5b3a997162ee5280\\u0026q-url-param-list\\u003d",
      "mesh_simplified_url": "https://hunyuan-3d-1258344703.cos.ap-guangzhou.myqcloud.com/gen_tmp_test/05abab7cfa854ddf933d8cde043e50d3/d032b44f2d38203b0aef7cba6f4608e5.ply?q-sign-algorithm\\u003dsha1\\u0026q-ak\\u003dAKID17Naks8SJQhxaN5jNBpGduztbwAMRWtK\\u0026q-sign-time\\u003d1787284421%3B1787370821\\u0026q-key-time\\u003d1787284421%3B1787370821\\u0026q-header-list\\u003d\\u0026q-url-param-list\\u003d\\u0026q-signature\\u003d6ef9239ed9f6bc757ad8b148bbc1896eaff756b1",
      "mesh_url": "https://hunyuan-3d-1258344703.cos.ap-guangzhou.myqcloud.com/gen_tmp_test/05abab7cfa854ddf933d8cde043e50d3/f8ba40403c32fa4702b0490235bbcd62.ply?q-sign-algorithm\\u003dsha1\\u0026q-ak\\u003dAKID17Naks8SJQhxaN5jNBpGduztbwAMRWtK\\u0026q-sign-time\\u003d1787284421%3B1787370821\\u0026q-key-time\\u003d1787284421%3B1787370821\\u0026q-header-list\\u003d\\u0026q-url-param-list\\u003d\\u0026q-signature\\u003d8f1d174827d6f8bf357a332c3bc0ece17d24a115",
      "point_url": "https://hunyuan-3d-1258344703.cos.ap-guangzhou.myqcloud.com/gen_tmp_test/05abab7cfa854ddf933d8cde043e50d3/2900cb7bcfd123395c258af86e89f620.ply?q-sign-algorithm\\u003dsha1\\u0026q-ak\\u003dAKID17Naks8SJQhxaN5jNBpGduztbwAMRWtK\\u0026q-sign-time\\u003d1787284420%3B1787370820\\u0026q-key-time\\u003d1787284420%3B1787370820\\u0026q-header-list\\u003d\\u0026q-url-param-list\\u003d\\u0026q-signature\\u003d318af6155121913d1f9c9334d68812a344dcec8d",
      "position_info": "{\\"up_direction\\": [0.08356333782703931, 0...",
      "scene_url": "https://hunyuan-3d-1258344703.cos.ap-guangzhou.myqcloud.com/gen_tmp_test/05abab7cfa854ddf933d8cde043e50d3/e632c15fcf66db300e39fff9d71ab8b1.spz?q-sign-algorithm\\u003dsha1\\u0026q-ak\\u003dAKID17Naks8SJQhxaN5jNBpGduztbwAMRWtK\\u0026q-sign-time\\u003d1787284418%3B1787370818\\u0026q-key-time\\u003d1787284418%3B1787370818\\u0026q-header-list\\u003d\\u0026q-url-param-list\\u003d\\u0026q-signature\\u003d6bbe2526c4ac2f155d65e1e6908ca2907d4e87e6",
      "super_resolution_image_url": "https://hunyuan-base-prod-1258344703.cos.ap-guangzhou.myqcloud.com/openapi/text2img/7fcbe0fe146d8d564fab2651886bab76.png?q-ak\\u003dAKIDRl074nOsGdJ9zjMsCRWP3ShmgS3VtX4S\\u0026q-header-list\\u003d\\u0026q-key-time\\u003d1787283327%3B1787369727\\u0026q-sign-algorithm\\u003dsha1\\u0026q-sign-time\\u003d1787283327%3B1787369727\\u0026q-signature\\u003d6eb63978c077a5637d77ba8bac558f9733f985c6\\u0026q-url-param-list\\u003d"
    }
  ],
  "id": "4-WandVideo-01105813c9e443ed977daa511a0700b3",
  "status": "succeeded",
  "version": "1",
  "tokenhub_usage": {
    "total_tokens": 8000000
  },
  "request_id": "450ffc9c-29fb-4549-80a7-ee48549189cd"
}

6. 状态码

status
含义
处理建议
queued
排队中
继续轮询。
running
生成中
每 3~5 秒轮询一次，直至 status=succeeded。
succeeded
生成成功
从 data 中获取各格式文件 URL。
failed
生成失败
服务端生成出错，请重试；持续失败请联系技术支持并附任务 id。
cancelled
已取消
任务已取消，需重新发起。
unknown
未知状态
请重试或联系技术支持。

上一篇: Hy 生视频调用指南下一篇: MiniMax 音乐生成调用指南

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档