文档中心

AI MediaKit

大模型处理工具

视频理解拓展工具

火山方舟视觉大模型可理解视频中的视觉信息，完成如描述其中的物体、分析动作逻辑等视觉相关任务。AI MediaKit 视频理解能力是对火山方舟平台视觉理解能力的工程级增强，依托视频云深厚的媒体处理基础设施，将 URL 传入方式的视频上限从 50 MB 放宽至 5 GB，满足工业级长视频、高码率素材的分析需求。

本篇开发指南将引导您：

快速体验让 AI 描述一段视频的核心内容。

掌握控制视频理解精细度、进行时序感知识别等进阶用法。

理解视频理解功能的工作原理与使用限制。

产品优势

大文件支持：通过视频 URL 传入方式，支持最高 5 GB 的大视频文件处理。

无缝迁移：接口协议完全兼容火山方舟 Chat API，仅需更换请求域名即可平滑迁移。

支持模型

请参见火山方舟视觉理解能力模型列表。

快速体验：让 AI 描述一段视频内容

本节将引导您完成一次最基础的视频理解任务：向 AI 提供一个视频 URL，并让它用自然语言描述视频内容。

准备工作

由于视频理解工具集成了火山方舟的模型推理与 AI MediaKit 的媒体处理能力，在发起请求前，您需要获取以下两类凭证：

1. 获取模型相关信息（火山方舟侧）

获取火山方舟 API Key：访问火山方舟控制台 API Key 管理页面，创建并获取火山方舟 API Key（用于模型推理鉴权）。

开通模型服务并获取模型 ID：访问火山方舟控制台开通管理页面，开通视觉理解相关模型服务，并获取对应的火山方舟模型 ID（Model ID）。

说明

模型列表：快速浏览方舟提供的模型全集以及各个模型所具备的能力，快速根据你的实际场景匹配到合适的模型。

2. 获取媒体处理凭证（AI MediaKit 侧）

访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key（用于视频拉取与预处理鉴权）。

操作方式

调用 AI MediaKit Chat API 通过公网可访问的视频 URL 传入视频，示例代码如下：

说明

在拷贝下方示例代码运行前，执行以下操作：

拼接并填入鉴权信息：将火山方舟 API Key 与 MediaKit API Key 用英文斜杠 / 拼接（格式为火山方舟Key/MediaKitKey），填入代码中的 api_key 或 Authorization 占位符处。

填写火山方舟模型 ID：将准备工作中获取的模型 ID 填入代码的 model 字段。

自定义提示词（可选）：根据您的实际需求，修改 text 字段中的提示词（Prompt）。

Curl

Python

Golang

Java

AI MediaKit 会利用视频云的媒体处理流水线执行以下操作：

拉取视频：从公网 URL 或云存储下载原始视频。

智能抽帧：根据您的 fps 设置（默认每秒 1 帧）提取视频帧。

序列转换：将视频转换为“时间戳 + 图片”的结构化序列。

模型推理：将转换后的多模态请求发送至火山方舟大模型获取结论。

注意

若您的视频文件小于 50 MB，或需要使用 Base64 编码、Files API 等方式传入视频，可直接调用火山方舟 API，详见火山方舟视频理解文档。

进阶使用

控制视频理解的精细度和 Token 成本

您可以通过组合使用 fps、max_frames 和 max_pixels 三个参数，精细地平衡视频理解的分析粒度与 Token 成本。

控制时间粒度 (fps)：通过 fps 字段控制抽帧频率，默认为 1（每秒 1 帧）。

若需分析快速变化的动作（如体育赛事中的进球瞬间），可适当调高 fps（最高为 5），以捕捉关键画面。

若视频内容变化平缓（如风景延时），可调低 fps（最低为 0.01），以加快处理并节省成本。

控制空间粒度 (max_pixels)：通过 max_pixels 字段限制单帧画面的最大分辨率（宽 × 高）。对于高分辨率视频（如 4K），如果不关心画面中的微小细节，可以设置一个较低的 max_pixels 值。系统会在分析前缩小图片尺寸，从而显著降低单帧画面的 Token 消耗。

控制总帧数上限 (max_frames)：通过 max_frames 字段为任务设定一个绝对的抽帧数量上限。这提供了一个独立于视频时长和 fps 的成本“熔断”机制，确保总帧数不会超过您的预期。

示例：在请求中设置抽帧参数

Curl

Python

Java

感知视频时序

视频理解可理解视频时间和图像关系信息，如回答事件发生在什么时间点，在哪些时间发生了某事件等和时间相关的信息，详见视频理解工作原理。您可在提示词中加入类似“请给出具体时间点”的要求。示例代码如下：

Curl

Python

Java

回复预览

流式输出

流式输出支持内容动态实时呈现，既能够缓解用户等待焦虑，又可以规避复杂任务因长时间推理引发的客户端超时失败问题，保障请求流程顺畅。

Curl

Python

Java

使用说明

说明

处理完视频后，文件会从火山服务器删除。火山不会保留您提交的视频以及文本信息等用户数据来训练模型。

时序信息

基于 FPS 的抽帧获取视频帧，再通过时间戳+图像拼接标记时序信息，模型基于该请求中的时序标记和图像内容，实现对视频的完整理解（包括内容变化、动作逻辑、时序关联等）。详细信息见视频理解工作原理。

视频格式说明

支持 MP4、FLV、ASF、RM、RMVB、MPEG、MOV、AVI、MPEGTS、M4S、WMV、3GP、TS、MPG、WEBM、MKV、MPE、VOB、DAT、MP4V、M4V、F4V、MXF、QT 等主流视频格式。

注意

视频文件格式变种较多，不能保证所有文件都能被识别，请通过测试验证文件能够被正常识别。

对于 HLS 格式视频，当您传入 M3U8 地址进行处理时，如果 M3U8 文件中含有 EXT-X-MAP 标签，目前暂不支持处理。

视频文件大小限制

使用 URL 方式传入视频，视频文件不能超过 5GB。

不支持音频理解

暂不支持对视频文件中的音频信息进行理解。

抽帧策略

AI MediaKit 视频理解服务内置了成本控制机制，默认将单次视频处理的总 Token 消耗限制在 200k 以内，确保任务稳定运行，避免超长视频或高分辨率素材导致上下文窗口溢出或费用失控。

抽帧决策遵循以下逻辑：

计算单帧 Token 成本：AI MediaKit 首先会检查您是否设置了 max_pixels 参数。如果视频原始分辨率（宽 × 高）超过 max_pixels 的限制，系统会先将图片等比缩小，然后再根据缩小后的分辨率，参考图片 token 用量估算规则估算单帧画面的 Token 消耗。

默认 max_pixels：若不设置，默认为 677,376。

最大 max_pixels：最大值为 9,031,680，超出部分按最大值计算。

计算预算内最大帧数：根据第一步算出的“单帧 Token 成本”，系统用总预算（200k Token）计算出在此成本下，最多能处理多少帧图像，这个数量即为 MaxFrames_budget。

抽帧方案判定：系统会综合评判 fps、max_frames 和 MaxFrames_budget，选择最严格的限制来执行抽帧：

首先，根据视频时长和用户设置的 fps 计算出一个理论抽帧数（理论帧数 = 时长 × fps）。

然后，如果用户还设置了 max_frames，则将理论抽帧数与 max_frames 取较小值，得到“用户期望帧数”。用户期望帧数 = min(时长 × fps, max_frames)

最后，将“用户期望帧数”与系统预算的 MaxFrames_budget 进行比较：

预算充足：如果用户期望帧数 ≤ MaxFrames_budget，系统将完全按照用户的设定（fps 和 max_frames）执行抽帧。

预算不足：如果用户期望帧数 > MaxFrames_budget（通常发生在长视频、高 fps 或高分辨率场景），系统将忽略用户设定的 fps 和 max_frames，强制采用 MaxFrames_budget 作为最终抽帧数，并在整个视频时长内均匀采样，以确保在不超预算的前提下，无论视频多长，模型都能获取覆盖全片的视觉信息，而不会因为超出窗口导致任务失败。

视频理解工作原理

视频处理的核心方式为 “帧与时间戳的结构化拼接”，具体规则如下：

对视频抽帧得到的每帧图像，在其前插入时间戳文本，格式为 [<时间戳> second]。

拼接后形成“时间戳+图像”的有序序列，模型通过该序列理解视频的时序逻辑和内容变化。

抽帧逻辑举例

	FPS 1	FPS 0.5	FPS 2
时间戳	[0.0 second]	[0.0 second]	[0.0 second]
视频帧	<IMAGE>	<IMAGE>	<IMAGE>
时间戳	[1.0 second]	[2.0 second]	[0.5 second]
视频帧	<IMAGE>	<IMAGE>	<IMAGE>
时间戳	[2.0 second]	[4.0 second]	[1.0 second]
视频帧	<IMAGE>	<IMAGE>	<IMAGE>
时间戳	[3.0 second]		[1.5 second]
视频帧	<IMAGE>		<IMAGE>
时间戳	[4.0 second]		[2.0 second]
视频帧	<IMAGE>		<IMAGE>
时间戳	[5.0 second]		[2.5 second]
视频帧	<IMAGE>		<IMAGE>
时间戳			[3.0 second]
视频帧			<IMAGE>
时间戳			[3.5 second]
视频帧			<IMAGE>
时间戳			[4.0 second]
视频帧			<IMAGE>
时间戳			[4.5 second]
视频帧			<IMAGE>
时间戳			[5.0 second]
视频帧			<IMAGE>
	共 6 帧	共 3 帧	共 11 帧

多图请求等效

视频理解请求等效于下面示例的多图理解请求。