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

本接口用于提交一个异步的图片转视频任务，将多张图片按顺序组合，并可选地配置转场动画和镜头内动画，最终生成一段动态视频。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
images	Array	是	-	图片对象列表，用于定义视频的每一帧内容。详细结构见下方的 Image 对象。数量限制：单次任务支持传入 1 到 100 个图片对象。
transitions	Array	否	["1182360"]	图片间的转场效果 ID 列表。默认无转场（硬切）。如果列表长度小于所需转场数（图片数量 - 1），将循环使用列表中的效果。详细 ID 见文末转场效果。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_131	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_unique_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

Image 对象

images 数组中的每个对象代表一张图片及其动画效果，包含以下字段：

参数	类型	是否必选	描述
image_url	String	是	图片的 URL。图片来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：jpg, png 等主流静态图片格式。
duration	Number	否	图片的展示时长（单位：秒）。支持最多两位小数，默认值为 3。
animation_type	String	否	图片在展示期间的镜头内动画类型。默认无动画。可选值如下： move_up：上移 move_down：下移 move_left：左移 move_right：右移 zoom_in：放大 zoom_out：缩小
animation_in	Number	否	动画开始的时间点（单位：秒），相对于该图片片段的起始。仅在设置了 animation_type 后生效。支持两位小数。默认值为 0，表示动画从图片展示的第一帧开始。
animation_out	Number	否	动画结束的时间点（单位：秒），相对于该图片片段的起始。仅在设置了 animation_type 后生效。支持两位小数。默认值为图片的 duration 值，表示动画在图片展示的最后一帧结束。

请求示例

以下示例演示了如何使用两张图片生成视频：

第一张图片展示 3 秒，并应用“放大”动画。

第二张图片展示 2.5 秒，并应用“向右移动”动画。

两张图片之间使用“旋转放大”(1182360) 转场效果。

响应说明

调用 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	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

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

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

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

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

参数	类型	示例	描述
video_url	String	"https://example.volcvideo.com/output.mp4?auth_key=..."	生成的视频文件地址。文件格式为 MP4。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	5.5	输出视频的总时长（单位：秒）。
resolution	String	"1080p"	输出视频的分辨率。

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

附录

转场效果

下表为当前支持的所有转场效果及其 ID。

效果名称	ID	动画展示
交替出场	1182359
旋转放大	1182360
泛开	1182358
六角形	1182365
故障转换	1182367
飞眼	1182368
梦幻放大	1182369
开门展现	1182370
立方转换	1182373
透镜变换	1182374
晚霞转场	1182375
圆形交替	1182378

AI MediaKit