Skip to content

Hy โ€‹

Updated

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 โ€‹

ItemValue
Call pathTokenhub API
Guardrail bypass supportNot supported

Supported Specifications by Version โ€‹

VersionResolutionRatioDuration
hy-video-v1.5720p16:9 / 9:16 / 1:1 / 4:3 / 3:45 seconds

Input Modes โ€‹

VersionInput
hy-video-v1.5Text-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.

  1. Submit the task: Call the video generation API. On success, task_id (the task ID) and request_id are returned.
  2. 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 from videos.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 โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel version. Value: hy-video-v1.5
promptConditionally requiredstringText 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_promptOptionalstringA negative prompt describing content that should not appear.
imageOptionalstringThe 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_urlOptionalstringA publicly accessible input image URL. Passing a URL uses image-to-video generation. Use either this parameter or image.
nOptionalintThe number of output videos.
durationOptionalnumberVideo duration in seconds. Decimal values are truncated to integers. The current version generates at a fixed duration of 5 seconds.
aspect_ratioOptionalstringRatio, valid only for text-to-video generation. Enumerated values: 16:9 / 9:16 / 1:1 / 4:3 / 3:4.
resolutionOptionalstringResolution. The current version outputs at a fixed resolution of 720p.
reviseOptionalboolWhether to enable intelligent prompt rewriting (an extension parameter passed through to the model service as-is).
moderationOptionalboolcontent moderation switch (an extension parameter passed through to the model service as-is).
seedOptionalintRandom seed (an extension parameter passed through to the model service as-is; whether it takes effect depends on the model side).
footnoteOptionalstringCustom 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:

bash
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):

bash
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):

bash
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.

FieldTypeDescription
task_idstringThe task ID generated by the system, used for subsequent task queries.
createdintegerTask creation time, as a Unix timestamp in seconds.
request_idstringThe unique ID of this request, used for troubleshooting and technical support.

On failed submission, the unified error response structure is returned.

FieldTypeDescription
task_idstringThe task ID (an empty string if creation failed).
statusstringFixed as failed.
error.codestringError code. See Appendix: Unified Error Codes.
error.messagestringError description.

Response Examples โ€‹

Submission succeeded:

json
{
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "created": 1787108411,
  "request_id": "835a268e-af02-4615-a30b-7e4b815e8839"
}

Submission failed:

json
{
  "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.

statusDescriptionRecommended handling
queuedSubmitted and awaiting schedulingContinue querying the state.
runningGeneratingContinue querying the state.
succeededGeneration succeededRetrieve the video URL from videos.url in the query result.
failedGeneration failedCheck 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 โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task ID (path parameter), which is the task_id returned when the task was submitted.

Request Example โ€‹

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

Response Parameters โ€‹

FieldTypeDescription
task_idstringTask ID.
statusstringTask state: queued (awaiting scheduling) / running (generating) / succeeded (succeeded) / failed (failed)
createdintegerTask creation time, as a Unix timestamp in seconds.
videosarrayThe array of video results (returned on success).
videos[].urlstringThe video file URL is a temporary URL. Download and save it immediately.
videos[].audio_urlstringThe audio file URL (an empty string if there is no audio).
videos[].generate_infostringAdditional information generated on the model side (an empty string if there is none).
tokenhub_usageobjectUsage (returned after the task reaches a final state and billing is complete).
tokenhub_usage.total_tokensintegerThe number of tokens consumed by this task, used for billing/settlement.
errorobjectFailure information (returned when status=failed). Contains code / message; null when there is no failure.
error.codestringError code.
error.messagestringError description.
request_idstringThe unique ID of this request, used for troubleshooting and technical support.

Response Examples โ€‹

Generating (running):

json
{
  "created": 1787108411,
  "error": null,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "running",
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

Generation succeeded:

json
{
  "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:

json
{
  "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 codeBusiness codeError messageDescription
2000SuccessThe request succeeded.
4011000Authentication failedAuthorization is missing or the apikey is invalid.
4011001Authorization is emptyThe Authorization header was not passed.
4011002Authorization is invalidThe apikey is invalid or has expired.
4011003Authorization is not yet validThe apikey is not yet valid.
4011004Authorization expiredThe apikey has expired.
4291100Account exceptionAccount exception (which may be caused by overdue payment, suspension, or a ban).
4291101Account overdue (postpaid)The postpaid account has an overdue balance.
4291102Resource pack exhausted or expiredThe resource pack has been fully used or has expired.
4031103Access to the requested resource deniedThe requested resource cannot be accessed (the corresponding model/feature is not subscribed).
4001200Bad request parameterThe request parameters are incorrect (a required field is missing, a type is wrong, an enumerated value is out of range, and so on).
4001201Invalid parameterThe parameter value is incorrect. Check the valid value range in the documentation.
4041202The requested method is invalidThe HTTP method is incorrect.
4041203The requested resource does not existThe endpoint path is incorrect or the resource does not exist.
4001300Platform policy triggeredA platform policy was triggered (content moderation failed or the input was non-compliant, and so on).
4001301Platform sensitive word list triggeredThe content contains sensitive words or non-compliant prompts.
4291302API calls are too frequentThe call frequency is too high and rate limiting has been applied.
4291303Concurrency or QPS limit exceededThe concurrency count or QPS exceeded the preset quota.
4001304IP policy triggeredBlocking based on an IP address policy was triggered.
5005000Internal server errorInternal server error.
5035001Server temporarily unavailableThe service is temporarily unavailable (usually due to high load or maintenance).
5045002Server internal timeoutInternal server timeout.

FAQ โ€‹

  1. 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.

  1. 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.

  1. 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.

  1. 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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages