POST https://mediakit.cn-beijing.volces.com/api/v1/tools/hyperframes-to-video

本 API 用于提交一个异步的 HyperFrames 云端渲染任务，将 ZIP 资源包中的 HTML 工程在云端逐帧渲染为视频，支持输出 MP4、WebM、MOV 或 GIF。该功能常用于口播视频片头、章节标题、产品介绍动画等场景。

请求参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。
Content-Type	String	是	application/json	请求体的媒体类型，固定为 application/json。

Body 参数

参数	类型	是否必选	示例值	描述
bundle_url	String	是	https://example.com/hyperframes/product-intro.zip	HyperFrames 工程 ZIP 包地址。目录结构：入口文件须命名为 index.html 并位于 ZIP 包根目录，工程依赖的资源需一并打包并通过相对路径引用。详细打包要求请参阅HyperFrames 工程包要求。输入来源：支持公网 HTTP/HTTPS URL。
quality	String	否	high	渲染质量档位。可选值： draft：草稿质量，渲染速度快，适用于快速预览。 standard：标准质量（默认）。 high：高质量，适用于最终出片。
bitrate	Integer	否	8000	目标平均码率，单位为 kbps，取值范围为 [10, 150000]。不设置时采用底层默认编码策略。对于 MOV（ProRes 编码）和 GIF 输出，该参数可能不生效。
format	String	否	mp4	输出格式。可选值： mp4：默认格式，适用于常规播放与分发。 webm：支持透明通道。 mov：支持透明通道。使用 ProRes 编码时 bitrate 可能不生效。 gif：输出动态图片。当 alpha 为 true 时，format 只能为 webm、mov 或 gif。
fps	Integer	否	30	输出帧率，取值范围为 [1, 60]。
alpha	Boolean	否	false	是否保留透明通道。设为 true 时，format 必须为 webm、mov 或 gif；若与 mp4 同时设置，请求将失败。
client_token	String	否	hyperframes_render_001	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	asset_id_20261021_001	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考按项目或 API Key 分账。

请求示例

以下示例演示了如何将一个 HyperFrames 工程渲染为 30 FPS、高质量、平均码率为 8000 kbps 的 MP4 视频。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

HyperFrames 云端渲染是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容：

参数	类型	示例值	描述
video_url	String	https://example.volcvideo.com/hyperframes/product-intro.mp4?auth_key=...	渲染产物的下载地址。该地址为临时下载链接，有效期为 24 小时，请及时下载保存。
duration	Number	12.5	输出产物的时长，单位为秒。GIF 产物可能返回 0。
resolution	String	1080p	输出产物的分辨率档位。可能值：240p、360p、480p、540p、720p、1080p、2k、4k、6k、8k。

最终的完整任务信息示例：

AI MediaKit