Hy โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generationAuthentication: Tokenhub API Key / Bearer
Hy Video 1.5 is Tencent Hunyuan's video generation model, generating videos from text or a first-frame image. After submitting a task, query the result by task ID.
Basic Information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Not supported |
Supported Specifications by Version โ
| Version | Resolution | Ratio | Duration |
|---|---|---|---|
hy-video-v1.5 | 720p | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 | 5 seconds |
Input Modes โ
| Version | Input |
|---|---|
hy-video-v1.5 | Text-to-video / image-to-video |
Call Procedure โ
Video generation is a long-running operation, so API uses an asynchronous call pattern, divided into the following two steps.
- Submit the task: Call the video generation API. On success,
task_id(the task ID) andrequest_idare returned. - Poll for the result: Call the Query task result API with the task ID until the state becomes
status = succeeded, then retrieve the video URL fromvideos.url.
Note: Responses in this API series do not use the unified code / message / data response structure. On successful submission, {"task_id": "...", "created": ..., "request_id": "..."} is returned; on query, a task object is returned (containing fields such as task_id / status / videos / usage). Task state values are unified as queued (awaiting scheduling) / running (generating) / succeeded (succeeded) / failed (failed).
Video Generation โ
API Description โ
Submits 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 (an image URL) is provided, it is an image-to-video task.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model version. Value: hy-video-v1.5 |
| prompt | Conditionally required | string | Text prompt. Required for text-to-video generation and optional for image-to-video generation (used to describe the motion of the reference target in the image). |
| negative_prompt | Optional | string | A negative prompt describing content that should not appear. |
| image | Optional | string | The input image encoded in Base64. Passing this parameter uses image-to-video generation. Use either this parameter or image_url. If both are passed, image takes precedence. |
| image_url | Optional | string | A publicly accessible input image URL. Passing a URL uses image-to-video generation. Use either this parameter or image. |
| n | Optional | int | The number of output videos. |
| duration | Optional | number | Video duration in seconds. Decimal values are truncated to integers. The current version generates at a fixed duration of 5 seconds. |
| aspect_ratio | Optional | string | Ratio, valid only for text-to-video generation. Enumerated values: 16:9 / 9:16 / 1:1 / 4:3 / 3:4. |
| resolution | Optional | string | Resolution. The current version outputs at a fixed resolution of 720p. |
| revise | Optional | bool | Whether to enable intelligent prompt rewriting (an extension parameter passed through to the model service as-is). |
| moderation | Optional | bool | content moderation switch (an extension parameter passed through to the model service as-is). |
| seed | Optional | int | Random seed (an extension parameter passed through to the model service as-is; whether it takes effect depends on the model side). |
| footnote | Optional | string | Custom watermark content. Whether Chinese or English, it is limited to 16 characters after removing line breaks and spaces, and is generated in the bottom-right corner of the video. |
Note: Apart from the fields listed in the table above, any other unrecognized fields are passed through to the model service as-is.
Request Examples โ
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>"
}'Response Parameters โ
On successful submission, the following is returned.
| Field | Type | Description |
|---|---|---|
| task_id | string | The task ID generated by the system, used for subsequent task queries. |
| created | integer | Task creation time, as a Unix timestamp in seconds. |
| request_id | string | The unique ID of this request, used for troubleshooting and technical support. |
On failed submission, the unified error response structure is returned.
| Field | Type | Description |
|---|---|---|
| task_id | string | The task ID (an empty string if creation failed). |
| status | string | Fixed as failed. |
| error.code | string | Error code. See Appendix: Unified Error Codes. |
| error.message | string | Error description. |
Response Examples โ
Submission succeeded:
{
"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"
}
}Error Codes โ
If a request fails, a response structure in the {"task_id":"","status":"failed","error":{...}} format is returned. For specific error codes and handling recommendations, see Appendix: Unified Error Codes. After a task is submitted successfully, the task state during the generation phase can be checked via Query task result API.
| status | Description | Recommended handling |
|---|---|---|
| queued | Submitted and awaiting scheduling | Continue querying the state. |
| running | Generating | Continue querying the state. |
| succeeded | Generation succeeded | Retrieve the video URL from videos.url in the query result. |
| failed | Generation failed | Check the cause of failure in error.message, fix it, and retry. If failures persist, contact technical support. |
Querying Task Results โ
API Description โ
After a task is submitted and a task ID is returned, poll the task state via the task query endpoint. On success, retrieve 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. Video generation takes roughly a few minutes, so polling every 3~5 seconds is recommended. The response passes through the model-side return packet as-is while adding platform-normalized fields, and may include original vendor fields not listed in the table below. Refer to the actual returned response.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task ID (path parameter), which is the task_id returned when the task was submitted. |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| task_id | string | Task ID. |
| status | string | Task state: queued (awaiting scheduling) / running (generating) / succeeded (succeeded) / failed (failed) |
| created | integer | Task creation time, as a Unix timestamp in seconds. |
| videos | array | The array of video results (returned on success). |
| videos[].url | string | The video file URL is a temporary URL. Download and save it immediately. |
| videos[].audio_url | string | The audio file URL (an empty string if there is no audio). |
| videos[].generate_info | string | Additional information generated on the model side (an empty string if there is none). |
| tokenhub_usage | object | Usage (returned after the task reaches a final state and billing is complete). |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing/settlement. |
| error | object | Failure information (returned when status=failed). Contains code / message; null when there is no failure. |
| error.code | string | Error code. |
| error.message | string | Error description. |
| request_id | string | The unique ID of this request, used for troubleshooting and technical support. |
Response Examples โ
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://result.example.com/generated-image.png"
}
],
"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"
}Error Codes โ
If a request fails, the unified error response structure is returned. For specific error codes and handling recommendations, see Appendix: Unified Error Codes. The task state descriptions are the same as those in "Video Generation".
Appendix โ
Unified Error Codes โ
| HTTP status code | Business code | Error message | Description |
|---|---|---|---|
200 | 0 | Success | The request succeeded. |
401 | 1000 | Authentication failed | Authorization is missing or the apikey is invalid. |
401 | 1001 | Authorization is empty | The Authorization header was not passed. |
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 expired | The apikey has expired. |
429 | 1100 | Account exception | Account exception (which may be caused by overdue payment, suspension, or a ban). |
429 | 1101 | Account overdue (postpaid) | The postpaid account has an overdue balance. |
429 | 1102 | Resource pack exhausted or expired | The resource pack has been fully used or has expired. |
403 | 1103 | Access to the requested resource denied | The requested resource cannot be accessed (the corresponding model/feature is not subscribed). |
400 | 1200 | Bad request parameter | The request parameters are incorrect (a required field is missing, a type is wrong, an enumerated value is out of range, and so on). |
400 | 1201 | Invalid parameter | The parameter value is incorrect. 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 | Platform policy triggered | A platform policy was triggered (content moderation failed or the input was non-compliant, and so on). |
400 | 1301 | Platform sensitive word list triggered | The content contains sensitive words or non-compliant prompts. |
429 | 1302 | API calls are too frequent | The call frequency is too high and rate limiting has been applied. |
429 | 1303 | Concurrency or QPS limit exceeded | The concurrency count or QPS exceeded the preset quota. |
400 | 1304 | IP policy triggered | Blocking based on an IP address policy was triggered. |
500 | 5000 | Internal server error | Internal server error. |
503 | 5001 | Server temporarily unavailable | The service is temporarily unavailable (usually due to high load or maintenance). |
504 | 5002 | Server internal timeout | Internal server timeout. |
FAQ โ
- How do I switch between text-to-video and image-to-video?
The mode is determined automatically by the input parameters. If neither image nor image_url is provided, it is text-to-video; if either image parameter is provided, it is image-to-video. If both image and image_url are provided, image (Base64) takes precedence.
- Which values are supported for video duration, resolution, and ratio?
In the current version, the video duration is fixed at 5 seconds and the resolution is fixed at 720p. The ratio aspect_ratio can only be specified for text-to-video (16:9 / 9:16 / 1:1 / 4:3 / 3:4); for image-to-video, the ratio is determined by the input image.
- Which state values does the query API return?
They are queued (awaiting scheduling) / running (generating) / succeeded (succeeded) / failed (failed). videos.url has a value only when the state is succeeded. When the state is failed, check the cause of failure in the error field.
- Can fields not listed in the documentation appear in the query response?
The query response passes through the model-side response as-is while adding platform-normalized fields (for example, usage.total_tokens and request_id). It may also contain other vendor-specific fields, which is normal. Refer to the actual response.