Hy
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation认证: Tokenhub API Key / Bearer
Hy Video 1.5 是腾讯混元的视频生成模型,可根据文本或首帧图片生成视频。提交任务后用任务 ID 查询结果。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 支持解除护栏 | 不支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
hy-video-v1.5 | 720p | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 | 5 秒 |
输入模式
| 版本 | 输入 |
|---|---|
hy-video-v1.5 | 文生视频 / 图生视频 |
调用流程
视频生成属于耗时较长的任务,因此 API 采用异步调用方式,分为以下两个步骤。
- 提交任务:调用视频生成 API。成功后会返回
task_id(任务 ID)和request_id。 - 轮询结果:用任务 ID 调用 查询任务结果 API,直到状态变为
status = succeeded,再从videos.url中获取视频 URL。
参考: 该 API 系列的响应不使用统一的 code / message / data 响应结构。提交成功时返回 {"task_id": "...", "created": ..., "request_id": "..."},查询时返回任务对象(包含 task_id / status / videos / usage 等字段)。任务状态取值统一为 queued(等待调度)/ running(生成中)/ succeeded(成功)/ failed(失败)。
视频生成
API 说明
提交文生视频或图生视频任务。未提供图片时为文生视频任务;提供 image(Base64)或 image_url(图片 URL)时则为图生视频任务。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型版本。取值:hy-video-v1.5 |
| prompt | 条件必填 | string | 文本提示词。文生视频时为必填,图生视频时为选填(用于描述图片中参考对象的运动)。 |
| negative_prompt | 选填 | string | 负向提示词,用于描述不应出现的内容。 |
| image | 选填 | string | 经 Base64 编码的输入图片。传入该参数时将使用图生视频。该参数与 image_url 二者择一使用。若两者都传入,则 image 优先。 |
| image_url | 选填 | string | 可公开访问的输入图片 URL。传入 URL 时将使用图生视频。该参数与 image 二者择一使用。 |
| n | 选填 | int | 输出视频数量。 |
| duration | 选填 | number | 视频时长(秒)。小数值会被截断为整数。当前版本按 5 秒 的固定时长生成。 |
| aspect_ratio | 选填 | string | 比例,仅对文生视频有效。枚举值:16:9 / 9:16 / 1:1 / 4:3 / 3:4。 |
| resolution | 选填 | string | 分辨率。当前版本按 720p 的固定分辨率输出。 |
| revise | 选填 | bool | 是否启用智能提示词改写(原样传给模型服务的扩展参数)。 |
| moderation | 选填 | bool | 内容审核开关(原样传给模型服务的扩展参数)。 |
| seed | 选填 | int | 随机种子(原样传给模型服务的扩展参数,是否生效取决于模型侧)。 |
| footnote | 选填 | string | 自定义水印内容。无论中文或英文,均限制为去除换行和空格后的 16 个字符,生成在视频右下角。 |
参考: 除上表列出的字段外,其他无法识别的字段会原样传给模型服务。
请求示例
文生视频:
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"
}'图生视频(图片 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"
}'图生视频(图片 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>"
}'响应参数
提交成功时会返回以下内容。
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 系统生成的任务 ID,用于后续任务查询。 |
| created | integer | 任务创建时间,为秒级 Unix 时间戳。 |
| request_id | string | 本次请求的唯一 ID,用于排查问题和技术支持。 |
提交失败时会返回统一的错误响应结构。
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务 ID(创建失败时为空字符串)。 |
| status | string | 固定为 failed。 |
| error.code | string | 错误码。请参考 附录:统一错误码。 |
| error.message | string | 错误说明。 |
响应示例
提交成功:
{
"task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
"created": 1787108411,
"request_id": "835a268e-af02-4615-a30b-7e4b815e8839"
}提交失败:
{
"task_id": "",
"status": "failed",
"error": {
"code": "1300",
"message": "Trigger the platform strategy"
}
}错误码
请求失败时会返回 {"task_id":"","status":"failed","error":{...}} 格式的响应结构。具体错误码和处理建议请参考 附录:统一错误码。任务提交成功后,生成阶段的任务状态可通过 查询任务结果 API 确认。
| status | 说明 | 处理建议 |
|---|---|---|
| queued | 已提交,等待调度中 | 继续查询状态。 |
| running | 生成中 | 继续查询状态。 |
| succeeded | 生成成功 | 请从查询结果的 videos.url 中获取视频 URL。 |
| failed | 生成失败 | 在 error.message 中确认失败原因并修正后重试。若持续失败,请联系技术支持。 |
查询任务结果
API 说明
任务提交并返回任务 ID 后,通过任务查询端点轮询任务状态。成功后从结果中获取视频 URL。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/{task_id}
参考: 路径中的 {task_id} 是提交任务时返回的 task_id。视频生成大约需要数分钟,建议每 3~5 秒 轮询一次。响应是在原样透传模型侧返回包的基础上,追加了平台归一化的字段,可能包含下表未列出的原始供应商字段。请以实际返回的响应为准。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 任务 ID(路径参数),即提交任务时返回的 task_id。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务 ID。 |
| status | string | 任务状态:queued(等待调度)/ running(生成中)/ succeeded(成功)/ failed(失败) |
| created | integer | 任务创建时间,为秒级 Unix 时间戳。 |
| videos | array | 视频结果数组(成功时返回)。 |
| videos[].url | string | 视频文件 URL 是临时 URL。请立即下载并保存。 |
| videos[].audio_url | string | 音频文件 URL(无音频时为空字符串)。 |
| videos[].generate_info | string | 模型侧生成的附加信息(无则为空字符串)。 |
| tokenhub_usage | object | 用量(任务达到终态且计费完成后返回)。 |
| tokenhub_usage.total_tokens | integer | 本次任务消耗的 token 数,用于计费/结算。 |
| error | object | 失败信息(status=failed 时返回)。包含 code / message,无失败时为 null。 |
| error.code | string | 错误码。 |
| error.message | string | 错误说明。 |
| request_id | string | 本次请求的唯一 ID,用于排查问题和技术支持。 |
响应示例
生成中(running):
{
"created": 1787108411,
"error": null,
"task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
"status": "running",
"request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}生成成功:
{
"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"
}生成失败:
{
"created": 1787108411,
"task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
"status": "failed",
"error": {
"code": "InternalServiceError",
"message": "generate video failed"
},
"request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}错误码
请求失败时会返回统一的错误响应结构。具体错误码和处理建议请参考 附录:统一错误码。任务状态说明与「视频生成」中的说明相同。
附录
统一错误码
| HTTP 状态码 | 业务码 | 错误信息 | 说明 |
|---|---|---|---|
200 | 0 | 成功 | 请求成功。 |
401 | 1000 | 认证失败 | 缺少 Authorization 或 apikey 无效。 |
401 | 1001 | Authorization 为空 | 未传入 Authorization 头。 |
401 | 1002 | Authorization 无效 | apikey 无效或已过期。 |
401 | 1003 | Authorization 尚未生效 | apikey 尚未生效。 |
401 | 1004 | Authorization 已过期 | apikey 已过期。 |
429 | 1100 | 账号异常 | 账号异常(可能由欠费、停用或封禁等原因导致)。 |
429 | 1101 | 账号欠费(后付费) | 后付费账号存在欠费金额。 |
429 | 1102 | 资源包耗尽或已过期 | 资源包已用尽或资源包已过期。 |
403 | 1103 | 拒绝访问所请求的资源 | 无法访问所请求的资源(未订阅相应模型/功能)。 |
400 | 1200 | 请求参数有误 | 请求参数有误(缺少必填字段、类型有误、枚举值超出范围等)。 |
400 | 1201 | 参数无效 | 参数值有误。请在文档中确认有效取值范围。 |
404 | 1202 | 所请求的方法无效 | HTTP 方法有误。 |
404 | 1203 | 所请求的资源不存在 | 端点路径有误或资源不存在。 |
400 | 1300 | 触发平台策略 | 触发了平台策略(内容审核未通过或输入不合规等)。 |
400 | 1301 | 触发平台敏感词列表 | 内容中包含敏感词或不合规的提示词。 |
429 | 1302 | API 调用过于频繁 | 调用频率过高,已触发限速。 |
429 | 1303 | 超出并发数或 QPS 限制 | 并发数或 QPS 超出预设配额。 |
400 | 1304 | 触发 IP 策略 | 触发了基于 IP 地址策略的拦截。 |
500 | 5000 | 内部服务器错误 | 内部服务器错误。 |
503 | 5001 | 服务器暂时不可用 | 服务暂时不可用(通常由高负载或维护导致)。 |
504 | 5002 | 服务器内部超时 | 内部服务器超时。 |
FAQ
- 如何在文生视频和图生视频之间切换?
模式会根据输入参数自动确定。若 image / image_url 均未提供,则为文生视频;若提供了其中任一图片参数,则为图生视频。若同时提供 image 和 image_url,则 image(Base64)优先。
- 视频时长、分辨率和比例支持哪些取值?
当前版本中,视频时长固定为 5 秒,分辨率固定为 720p。比例 aspect_ratio 仅可在文生视频时指定(16:9 / 9:16 / 1:1 / 4:3 / 3:4),图生视频的比例由输入图片决定。
- 查询 API 会返回哪些状态值?
为 queued(等待调度)/ running(生成中)/ succeeded(成功)/ failed(失败)。只有状态为 succeeded 时,videos.url 才有值。状态为 failed 时,请在 error 字段中确认失败原因。
- 查询响应中会出现文档未列出的字段吗?
查询响应是在原样透传模型侧响应的基础上,追加了平台归一化的字段(例如 usage.total_tokens 和 request_id)。也可能包含其他供应商特有的字段,这属于正常情况。请以实际响应为准。