大模型服务平台 TokenHub Hy 生视频调用指南

二、前提条件

·已 注册腾讯云 账号并开通 TokenHub 服务。

·已在 TokenHub 控制台 获取 API Key。

·在控制台-在线推理-视觉模型 处开启对应模型的后付费。

注意：说明：

注意：下文所有示例中的 YOUR_API_KEY 均需替换为你自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

三、调用流程

视频生成为耗时任务，接口采用异步调用模式，统一分两步：

1. 提交任务：调用视频生成接口，成功返回 task_id（任务 ID）和 request_id；

2. 轮询结果：携带任务 ID 调用 查询任务结果 接口，直至 status = succeeded，从 videos[].url 获取视频地址。

注意：本系列接口响应不使用 code / message / data 统一信封：提交成功返回 {"task_id": "…", "created": …, "request_id": "…"}，查询返回任务对象（含 task_id / status / videos / usage 等字段）。任务状态统一为：queued（等待调度）/ running（生成中）/ succeeded（成功）/ failed（失败）。

四、模型列表

注意：说明：

六、1. 接口描述

提交文生视频或图生视频任务：不携带图片即为文生视频；携带 image（Base64）或 image_url（图片 URL）即为图生视频。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/hunyuan-video/generation

七、2. 输入参数

注意：除上表字段外，其余未识别字段将原样透传至模型服务；

八、3. 请求示例

文生视频：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/hunyuan-video/generation' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy-video-v1.5", "prompt": "一只小狗在草地上奔跑，阳光明媚", "negative_prompt": "模糊、变形", "aspect_ratio": "16:9"}'

图生视频（图片 URL）：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/hunyuan-video/generation' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy-video-v1.5", "prompt": "让图片中的主体自然转头，微风吹动头发", "image_url": "https://example.com/start.jpg"}'

图生视频（图片 Base64）：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/hunyuan-video/generation' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy-video-v1.5", "prompt": "镜头缓慢推进", "image": "<BASE64_ENCODED_IMAGE>"}'

九、4. 输出参数

提交成功返回：

提交失败返回统一错误信封：

十、5. 响应示例

提交成功：

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

十一、6. 错误码

请求失败时返回 {"task_id":"","status":"failed","error":{…}} 信封，具体错误码及处理建议请参见 附录：统一错误码。任务提交成功后，生成阶段的任务状态通过 查询任务结果 接口获取：

十三、1. 接口描述

提交任务返回任务 ID 后，通过任务查询端点轮询任务状态，成功后从结果中获取视频地址。

接口： GET https://tokenhub.tencentmaas.com/v1/wand/hunyuan-video/tasks/{task_id}

注意：说明：

注意：路径中的 {task_id} 即提交任务时返回的 task_id（示例中以 YOUR_TASK_ID 占位）。视频生成约需数分钟，建议每 3~5 秒轮询一次。响应为模型侧回包透传并叠加平台归一化字段，可能包含下表之外的原厂字段，以实际返回为准。

十四、2. 输入参数

十五、3. 请求示例

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

十六、4. 输出参数

十七、5. 响应示例

生成中（running）：

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

生成成功（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"}

生成失败（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. 错误码

请求失败时返回统一错误信封，具体错误码及处理建议请参见 附录：统一错误码。任务状态说明同「视频生成」。

20、统一错误码

21、常见问题

1. 文生视频和图生视频如何切换？

由入参自动区分：不携带 image / image_url 即为文生视频；携带任一图片参数即为图生视频。image 与 image_url 同时传入时以 image（Base64）为准。

2. 视频时长、清晰度、宽高比支持哪些取值？

当前版本视频时长固定 5 秒、清晰度固定 720p；宽高比 aspect_ratio 仅文生视频可指定（16:9 / 9:16 / 1:1 / 4:3 / 3:4），图生视频的画面比例由输入图片决定。

3. 查询接口返回的 status 有哪些？

queued（等待调度）/ running（生成中）/ succeeded（成功）/ failed（失败）。仅 succeeded 时 videos[].url 有值；failed 时查看 error 字段获取失败原因。

4. 查询响应里出现了文档未列出的字段？

查询响应为模型侧回包透传并叠加平台归一化字段（如 usage.total_tokens、request_id），可能包含其他原厂字段，均属正常，以实际返回为准。