tencent cloud

LLM Service TokenHub

ドキュメントLLM Service TokenHubAPI Integration Guide3D Generation ModelsHy World Model API Guide

Hy World Model API Guide

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-28 16:40:35
AI翻訳

Overview

Hy World Model is a new-generation multimodal world model dedicated to bridging the boundary between virtual and real worlds. It has powerful cross-modal cognitive capabilities and can generate vivid, high-fidelity 3D scenes or 360° panoramas from text descriptions or images.
This document describes how to call Hy 3D scene models through TokenHub: Hy-World-2.1-scene and Hy-World-2.1-panorama.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Enable postpaid billing for the corresponding model in Console - Online Inference - Vision Models.
Note:
In all examples below, YOUR_API_KEY must be replaced with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Call Process

The two types of APIs use different calling modes:
API Type
Description
360° Panorama (Synchronous API)
A single call directly returns the generated result without polling.
3D Scene Generation (Asynchronous API)
Time-consuming task (typically 10 to 20 minutes), called in two steps:
1. Submit a task: Call the capability API (text-to-scene/image-to-scene). A task id is returned upon success.
2. Poll for results: Call the query task result API with the id. It is recommended to poll every 3 to 5 seconds until status = succeeded (generation successful).
Note:
Do not resubmit the task after it is created successfully. Obtain the result by polling.

Model List

Model Name
model Parameter Value
Supported Capability
Model Description
HY-World-2.1-scene
hy-world2-scene
3D Scene Generation
Interactive, spatial 3D scene.
HY-World-2.1-panorama
hy-world2-panorama
360° Panorama Generation
Scene image viewable in 360 degrees.

3D Scene Generation

1. API Description

Generate interactive, walkable physical 3D scenes from text or images.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/world2-scene

2. Input Parameters

Parameter Name
Required
Type
Description
prompt
Yes
string
Text prompt that describes the desired scene content. Value range: ≤ 600 characters.
image_url
Conditionally required
string
Image URL. Pass a publicly accessible image URL. The minimum resolution is 512*512, and the file size cannot exceed 10M.
Supported formats: JPG, JPEG, PNG, and WEBP.
model
Conditionally required
string
Model version. Value range: hy-world2-scene
Note:
3D scene generation supports only text or image input (choose one). Simultaneous text and image input is not currently supported.

3. Request Example

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. Output Parameters

Field
Type
Description
id
string
Task ID, used to poll for task status.
request_id
string
Unique request identifier, used for troubleshooting.

5. Response Example


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

6. Status Codes

After the task is submitted successfully, poll the query task result API. The meanings of the status field are as follows:
status
Description
Handling Recommendation
queued
Queued
Continue polling.
running
Generating
Poll once every 3 to 5 seconds until status=succeeded.
succeeded
Succeeded
Obtain the URLs of files in each format from data.
failed
Generation failed.
Generation failed on the server. Retry. If the failure persists, contact technical support and provide the task id.
cancelled
Canceled
The task has been canceled. Initiate it again.
unknown
Unknown status.
Retry or contact technical support.

360° Panorama

1. API Description

Generate a panoramic image that can be viewed in 360 degrees from text or an image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/world2-panorama

2. Input Parameters

Parameter Name
Required
Type
Description
prompt
Yes
string
Text prompt that describes the desired scene content. Value range: ≤ 600 characters.
images
No
array of string
List of image URLs. Pass publicly accessible image URLs. The minimum resolution is 512*512, and the file size cannot exceed 10M.
Supported formats: JPG, JPEG, PNG, and WEBP.
model
Yes
string
Model version. Value range: hy-world2-panorama

3. Request Example

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": "Interior panorama of a modern art museum, soft natural light"
}'

4. Output Parameters

Field
Type
Description
id
string
Unique ID of this request.
created
integer
Request creation time (Unix timestamp).
status
string
Task status: succeeded / failed.
data
array
List of generated results.
data[].cover_image_url
string
Cover image URL for quick preview.
data[].super_resolution_image_url
string
Super-resolution panoramic image URL (primary output).
request_id
string
Unique request identifier, used for troubleshooting.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Response Example


{
    "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. Response Status Codes

Synchronous APIs return results directly. The meanings of the status field are as follows:
status
Description
Handling Recommendation
succeeded
Succeeded
Obtain the panoramic image from data[].super_resolution_image_url.
failed
Generation failed.
Check the input parameters and retry. If the failure persists, contact technical support and provide the id.

Querying the Task Result

1. API Description

3D scene generation is an asynchronous API. After the task is submitted, poll this API to obtain the generation result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/{task_id}
Note:
The {task_id} in the path is the id returned when the task is submitted (represented by YOUR_TASK_ID in the example). Generation takes approximately 10 to 20 minutes. It is recommended to poll every 3 to 5 seconds.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID (path parameter), which is the id returned when the task is submitted.

3. Request Example

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

4. Output Parameters

Field
Type
Description
id
string
Unique ID of this request.
created
integer
Request creation time (Unix timestamp).
status
string
Task status: queued / running / succeeded / failed / cancelled / unknown.
data
array
List of generated results (available when status=succeeded).
data[].image_url
string
Scene rendering preview image URL.
data[].scene_url
string
URL of the 3DGS scene file in SPZ format.
data[].point_url
string
URL of the 3D point cloud file in PLY format.
data[].mesh_url
string
URL of the complete collision mesh in PLY format.
data[].mesh_simplified_url
string
URL of the simplified collision mesh in PLY format, used for real-time collision detection on the frontend.
data[].position_info
string
JSON containing scene spatial position information, including up_direction, facing_direction, center_point, scale, and boundary coordinates.
data[].super_resolution_image_url
string
Super-resolution rendered image URL.
request_id
string
Unique request identifier, used for troubleshooting.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Response Example

Generation succeeded:

{
  "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 Codes

status
Description
Handling Recommendation
queued
Queued
Continue polling.
running
Generating
Poll once every 3 to 5 seconds until status=succeeded.
succeeded
Succeeded
Obtain the URLs of files in each format from data.
failed
Generation failed.
Generation failed on the server. Retry. If the failure persists, contact technical support and provide the task id.
cancelled
Canceled
The task has been canceled. Initiate it again.
unknown
Unknown status.
Retry or contact technical support.

前の記事へ: Hy Video Generation API Guide次の記事へ: MiniMax Music Generation API Guide

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック

キーワードで検索
    Enter keywords to search documentation