跳到内容

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.5720p16:9 / 9:16 / 1:1 / 4:3 / 3:45 秒

输入模式 ​

版本输入
hy-video-v1.5文生视频 / 图生视频

调用流程 ​

视频生成属于耗时较长的任务,因此 API 采用异步调用方式,分为以下两个步骤。

  1. 提交任务:调用视频生成 API。成功后会返回 task_id(任务 ID)和 request_id。
  2. 轮询结果:用任务 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 个字符,生成在视频右下角。

参考: 除上表列出的字段外,其他无法识别的字段会原样传给模型服务。

请求示例 ​

文生视频:

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"
}'

图生视频(图片 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"
}'

图生视频(图片 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>"
}'

响应参数 ​

提交成功时会返回以下内容。

字段类型说明
task_idstring系统生成的任务 ID,用于后续任务查询。
createdinteger任务创建时间,为秒级 Unix 时间戳。
request_idstring本次请求的唯一 ID,用于排查问题和技术支持。

提交失败时会返回统一的错误响应结构。

字段类型说明
task_idstring任务 ID(创建失败时为空字符串)。
statusstring固定为 failed。
error.codestring错误码。请参考 附录:统一错误码。
error.messagestring错误说明。

响应示例 ​

提交成功:

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

提交失败:

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

请求示例 ​

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

响应参数 ​

字段类型说明
task_idstring任务 ID。
statusstring任务状态:queued(等待调度)/ running(生成中)/ succeeded(成功)/ failed(失败)
createdinteger任务创建时间,为秒级 Unix 时间戳。
videosarray视频结果数组(成功时返回)。
videos[].urlstring视频文件 URL 是临时 URL。请立即下载并保存。
videos[].audio_urlstring音频文件 URL(无音频时为空字符串)。
videos[].generate_infostring模型侧生成的附加信息(无则为空字符串)。
tokenhub_usageobject用量(任务达到终态且计费完成后返回)。
tokenhub_usage.total_tokensinteger本次任务消耗的 token 数,用于计费/结算。
errorobject失败信息(status=failed 时返回)。包含 code / message,无失败时为 null。
error.codestring错误码。
error.messagestring错误说明。
request_idstring本次请求的唯一 ID,用于排查问题和技术支持。

响应示例 ​

生成中(running):

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

生成成功:

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"
}

生成失败:

json
{
  "created": 1787108411,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "failed",
  "error": {
    "code": "InternalServiceError",
    "message": "generate video failed"
  },
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

错误码 ​

请求失败时会返回统一的错误响应结构。具体错误码和处理建议请参考 附录:统一错误码。任务状态说明与「视频生成」中的说明相同。

附录 ​

统一错误码 ​

HTTP 状态码业务码错误信息说明
2000成功请求成功。
4011000认证失败缺少 Authorization 或 apikey 无效。
4011001Authorization 为空未传入 Authorization 头。
4011002Authorization 无效apikey 无效或已过期。
4011003Authorization 尚未生效apikey 尚未生效。
4011004Authorization 已过期apikey 已过期。
4291100账号异常账号异常(可能由欠费、停用或封禁等原因导致)。
4291101账号欠费(后付费)后付费账号存在欠费金额。
4291102资源包耗尽或已过期资源包已用尽或资源包已过期。
4031103拒绝访问所请求的资源无法访问所请求的资源(未订阅相应模型/功能)。
4001200请求参数有误请求参数有误(缺少必填字段、类型有误、枚举值超出范围等)。
4001201参数无效参数值有误。请在文档中确认有效取值范围。
4041202所请求的方法无效HTTP 方法有误。
4041203所请求的资源不存在端点路径有误或资源不存在。
4001300触发平台策略触发了平台策略(内容审核未通过或输入不合规等)。
4001301触发平台敏感词列表内容中包含敏感词或不合规的提示词。
4291302API 调用过于频繁调用频率过高,已触发限速。
4291303超出并发数或 QPS 限制并发数或 QPS 超出预设配额。
4001304触发 IP 策略触发了基于 IP 地址策略的拦截。
5005000内部服务器错误内部服务器错误。
5035001服务器暂时不可用服务暂时不可用(通常由高负载或维护导致)。
5045002服务器内部超时内部服务器超时。

FAQ ​

  1. 如何在文生视频和图生视频之间切换?

模式会根据输入参数自动确定。若 image / image_url 均未提供,则为文生视频;若提供了其中任一图片参数,则为图生视频。若同时提供 image 和 image_url,则 image(Base64)优先。

  1. 视频时长、分辨率和比例支持哪些取值?

当前版本中,视频时长固定为 5 秒,分辨率固定为 720p。比例 aspect_ratio 仅可在文生视频时指定(16:9 / 9:16 / 1:1 / 4:3 / 3:4),图生视频的比例由输入图片决定。

  1. 查询 API 会返回哪些状态值?

为 queued(等待调度)/ running(生成中)/ succeeded(成功)/ failed(失败)。只有状态为 succeeded 时,videos.url 才有值。状态为 failed 时,请在 error 字段中确认失败原因。

  1. 查询响应中会出现文档未列出的字段吗?

查询响应是在原样透传模型侧响应的基础上,追加了平台归一化的字段(例如 usage.total_tokens 和 request_id)。也可能包含其他供应商特有的字段,这属于正常情况。请以实际响应为准。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages