tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideVideo Generation ModelHy API Guide

Hy API Guide

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-10 22:08:17
Diterjemahkan oleh AI

Overview

Tencent Hunyuan Video Generation is an API-based technical service that provides video generation and video processing capabilities. Built on Tencent's video generation foundation model and a range of leading audio-video AI technologies, the service supports high-quality generation and processing of video content. It helps professional video creators reduce production costs and discover creative ideas, while also enhancing the entertainment value of video-based social interactions. The service can be widely applied in fields such as short video platforms, film and television production, advertising and marketing, social media, and gaming.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
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

Video generation is a time-consuming task, so the API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call the video generation API, which returns a task_id (task ID) and a request_id upon success.
2. Poll for results: Call the query task result API with the task ID until status = succeeded, and obtain the video URL from videos[].url.
Note:
The API responses in this series do not use the unified code / message / data envelope. A successful submission returns {"task_id": "...", "created": ..., "request_id": "..."}, and a query returns the task object (including fields such as task_id / status / videos / usage). Task status values are unified as: queued (waiting for scheduling) / running (generating) / succeeded (successful) / failed (failed).

Model List

Model Name
Model Parameter Value (Model ID)
Supported Capability
Video Duration (s)
Resolution Tier
Aspect Ratio
Selection Recommendations
Hy-Video-1.5
hy-video-v1.5
Text-to-video / image-to-video
5
720p
16:9, 9:16, 1:1, 4:3, 3:4 (only text-to-video can specify)
A general-purpose Hunyuan video model with integrated text-to-video/image-to-video capabilities.
Note:
Text-to-video / image-to-video are automatically distinguished by whether an image input parameter is included: if image or image_url is provided, it is image-to-video; otherwise, it is text-to-video.
The aspect ratio of image-to-video is determined by the input image, and the aspect_ratio parameter is not supported.

Video Generation

1. API Description

Submit a text-to-video or image-to-video task: if no image is provided, it is a text-to-video task; if image (Base64) or image_url (image URL) is provided, it is an image-to-video task.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value: hy-video-v1.5
prompt
Conditionally required
string
Text prompt. Required for text-to-video generation; optional for image-to-video generation (used to describe the motion of the subject in the image).
negative_prompt
No
string
Negative prompt, describing content that is not expected to appear.
image
No
string
Base64-encoded input image. If this parameter is carried, image-to-video generation is used. Use either this parameter or image_url; if both are passed, image takes precedence.
image_url
No
string
Publicly accessible URL of the input image. If the URL is carried, image-to-video generation is used. Use either this parameter or image.
n
No
int
Number of output videos.
duration
No
number
Video duration in seconds. Decimal values are truncated to integers. The current version generates a fixed duration of 5 seconds.
aspect_ratio
No
string
Aspect ratio, valid only for text-to-video generation. Enumerated values: 16:9 / 9:16 / 1:1 / 4:3 / 3:4.
resolution
No
string
Resolution. The current version outputs a fixed resolution of 720p.
revise
No
bool
Whether to enable intelligent prompt rewriting (an extended parameter passed through to the model service as is).
moderation
No
bool
Content moderation switch (an extended parameter passed through to the model service as is).
seed
No
int
Random seed (an extended parameter passed through to the model service as is; whether it takes effect depends on the model side).
footnote
No
string
Custom watermark content, limited to 16 characters (regardless of Chinese or English, with line breaks and spaces removed), generated in the lower right corner of the video.
Note:
Except for the fields listed in the table above, other unrecognized fields will be passed through to the model service as-is.

3. Sample Request

Text-to-video:
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "A puppy is running on the grass under bright sunshine."
  "negative_prompt": "blurry, distorted"
  "aspect_ratio": "16:9"
}'
Image-to-video (image URL):
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "Make the subject in the image turn its head naturally, with a gentle breeze blowing through its hair."
  "image_url": "https://example.com/start.jpg"
}'
Image-to-video (image Base64):
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "The camera slowly moves in",
  "image": "<BASE64_ENCODED_IMAGE>"
}'

4. Output Parameters

On successful submission, the following is returned:
Field
Type
Description
task_id
string
Task ID generated by the system, used for subsequent task queries.
created
integer
Task creation time, Unix timestamp in seconds.
request_id
string
Unique ID of this request, used for troubleshooting and technical support.
On submission failure, a unified error envelope is returned:
Field
Type
Description
task_id
string
Task ID (empty string if creation fails).
status
string
Fixed failed.
error.code
string
error.message
string
Error description.

5. Sample Response

Submitted successfully:
{
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "created": 1787108411,
  "request_id": "835a268e-af02-4615-a30b-7e4b815e8839"
}
Submission failed:
{
  "task_id": "",
  "status": "failed",
  "error": {
    "code": "1300",
    "message": "Trigger the platform strategy"
  }
}

6. Error Codes

When a request fails, an envelope in the format of {"task_id":"","status":"failed","error":{...}} is returned. For specific error codes and handling suggestions, see Appendix: Unified Error Codes. After a task is submitted successfully, the task status during the generation phase can be obtained through the Query Task Result API:
status
Description
Handling Recommendation
queued
Submitted and waiting for scheduling
Keep polling.
running
Generating
Keep polling.
succeeded
Generation succeeded
Obtain the video URL from the query result videos[].url.
failed
Generation failed
Check the failure cause in error.message, make modifications, and retry. If the failure persists, contact technical support.

Querying the Task Result

1. API Description

After a task is submitted and a task ID is returned, poll the task status through the task query endpoint. Upon success, obtain the video URL from the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/{task_id}
Note:
The {task_id} in the path is the task_id returned when the task was submitted (represented by YOUR_TASK_ID in the example). Video generation takes approximately several minutes, so polling every 3 to 5 seconds is recommended. The response is a pass-through of the model-side return packet with platform-normalized fields added, and may contain original vendor fields not listed in the following table. The actual returned response prevails.

2. Input Parameters

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

3. Sample Request

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
task_id
string
Task ID.
status
string
Task status: queued (pending scheduling) / running (generating) / succeeded (successful) / failed (failed)
created
integer
Task creation time, Unix timestamp in seconds.
videos
array
Array of video results (returned on success).
videos[].url
string
The video file URL is temporary. Download and save it promptly.
videos[].audio_url
string
Audio file URL (empty string when no audio is available).
videos[].generate_info
string
Additional information generated on the model side (empty string if none).
tokenhub_usage
object
Usage consumption (returned after the task reaches a final state and billing is completed).
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.
error
object
Failure information (returned when status=failed), including code / message; null if no failure.
error.code
string
Error code.
error.message
string
Error description.
request_id
string
Unique ID of this request, used for troubleshooting and technical support.

5. Sample Response

Generating (running):
{
  "created": 1787108411,
  "error": null,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "running",
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}
Generation succeeded:
{
  "created": 1787108411,
  "error": null,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "succeeded",
  "videos": [
    {
      "audio_url": "",
      "generate_info": "",
      "url": "https://aigc-output-video-1326893053.cos.ap-guangzhou.myqcloud.com/251435731/251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20_0.mp4?q-sign-algorithm=sha1&..."
    }
  ],
  "tokenhub_usage": {
    "total_tokens": 150000
  },
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}
Generation failed:
{
  "created": 1787108411,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "failed",
  "error": {
    "code": "InternalServiceError",
    "message": "generate video failed"
  },
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

6. Error Codes

When a request fails, a unified error envelope is returned. For specific error codes and handling suggestions, see Appendix: Unified Error Codes. The task status description is the same as that in "Video Generation".

Appendix

Unified Error Codes

HTTP Status Code
Business Code
Error Message
Description
200
0
success
Request succeeded.
401
1000
Authentication failed
Authorization is missing or the apikey is invalid.
401
1001
Authorization is empty
The Authorization header is not carried.
401
1002
Authorization is invalid
The apikey is invalid or has expired.
401
1003
Authorization is not yet valid
The apikey is not yet valid.
401
1004
Authorization has expired
The apikey has expired.
429
1100
Account exception
Account exception (possibly due to overdue payment, suspension, or ban).
429
1101
Account in arrears (postpaid)
The postpaid account has an overdue payment.
429
1102
Resource pack depleted or expired
The resource pack has been used up or has expired.
403
1103
Access denied for the requested resource
No access to the requested resource (the corresponding model/capability is not subscribed).
400
1200
Invalid request parameters
Invalid request parameters (missing required fields, incorrect types, out-of-range enum values, and so on).
400
1201
Invalid parameters
Invalid parameter value. Check the valid value range in the documentation.
404
1202
The requested method is invalid
The HTTP method is incorrect.
404
1203
The requested resource does not exist
The endpoint path is incorrect or the resource does not exist.
400
1300
Trigger the platform strategy
Triggers a platform policy (such as failed content moderation or non-compliant input).
400
1301
Trigger platform sensitive word list
The content contains sensitive words or non-compliant prompts.
429
1302
Too frequent API calls
The calls are too frequent, triggering rate limiting.
429
1303
Concurrency or QPS exceeds the limit
The concurrency or QPS exceeds the preset quota.
400
1304
Trigger IP strategy
Triggers IP address policy-based interception.
500
5000
Internal server error
Internal server error.
503
5001
Server is temporarily unavailable
The service is temporarily unavailable (usually due to high load or maintenance).
504
5002
Server internal timeout
Internal server timeout.

FAQs

1. How do I switch between text-to-video and image-to-video?
The mode is automatically determined by the input parameters: if neither image / image_url is provided, it is text-to-video; if either image parameter is provided, it is image-to-video. When both image and image_url are provided, image (Base64) takes precedence.
2. What values are supported for video duration, resolution, and aspect ratio?
In the current version, the video duration is fixed at 5 seconds and the resolution is fixed at 720p. The aspect ratio aspect_ratio can be specified only for text-to-video (16:9 / 9:16 / 1:1 / 4:3 / 3:4), while the aspect ratio of image-to-video is determined by the input image.
3. What status values does the query API return?
queued (waiting for scheduling) / running (generating) / succeeded (successful) / failed (failed). videos[].url has a value only when the status is succeeded. When the status is failed, check the error field to obtain the failure reason.
4. Did fields not listed in the documentation appear in the query response?
The query response is a pass-through of the model-side response with platform-normalized fields added (such as usage.total_tokens and request_id). It may also contain other vendor-specific fields, which is normal. The actual response prevails.




Topik sebelumnya: MiniMax API GuideTopik selanjutnya: CodeBuddy Code

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation