[火山方舟视觉大模型](https://www.volcengine.com/docs/82379/1330310?lang=zh#ff5ef604)可理解视频中的视觉信息，完成如描述其中的物体、分析动作逻辑等视觉相关任务。**AI MediaKit 视频理解能力**是对火山方舟平台视觉理解能力的工程级增强，依托视频云深厚的媒体处理基础设施，将 URL 传入方式的视频上限从 50 MB 放宽至 **5 GB**，满足工业级长视频、高码率素材的分析需求。本篇开发指南将引导您： * 快速体验让 AI 描述一段视频的核心内容。 * 掌握控制视频理解精细度、进行时序感知识别等进阶用法。 * 理解视频理解功能的工作原理与使用限制。 ## 产品优势 * **大文件支持**：通过视频 URL 传入方式，支持最高 **5 GB ** 的大视频文件处理。 * **无缝迁移**：接口协议完全兼容火山方舟 Chat API，仅需更换请求域名即可平滑迁移。 ## 支持模型请参见火山方舟[视觉理解能力模型列表](https://www.volcengine.com/docs/82379/1330310?lang=zh#ff5ef604)。 ## 快速体验：让 AI 描述一段视频内容本节将引导您完成一次最基础的视频理解任务：向 AI 提供一个视频 URL，并让它用自然语言描述视频内容。 :::tip AI MediaKit 的新用户？请参见[快速入门：视频理解前处理](/docs/6448/2222231)完成创建 API Key 及开通模型等准备工作。 ::: 调用 AI MediaKit [Chat API](https://www.volcengine.com/docs/6448/2210221?lang=zh) 通过公网可访问的视频 URL 传入视频，示例代码如下： :::tip 在拷贝下方示例代码运行前，执行以下操作： * **拼接并填入鉴权信息**：将**火山方舟 API Key ** 与 **MediaKit API Key** 用英文斜杠 `/` 拼接（格式为`火山方舟Key/MediaKitKey`），填入代码中的 `api_key` 或 `Authorization` 占位符处。 * **填写火山方舟模型 ID**：将准备工作中获取的模型 ID 填入代码的 `model` 字段。 * **自定义提示词（可选）** ：根据您的实际需求，修改 `text` 字段中的提示词（Prompt）。 ::: ```mixin-react return ( messages = new ArrayList<>(); final List multiContents = new ArrayList<>(); final ChatCompletionContentPart textPart = ChatCompletionContentPart.builder().type("text").text("总结描述视频的主要内容？").build(); multiContents.add(textPart); final ChatCompletionContentPart.ChatCompletionContentPartVideoURL videoURL = new ChatCompletionContentPart.ChatCompletionContentPartVideoURL("https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4", 2.0); final ChatCompletionContentPart videoPart = ChatCompletionContentPart.builder().type("video_url").videoUrl(videoURL).build(); multiContents.add(videoPart); final ChatMessage userMessage1 = ChatMessage.builder().role(ChatMessageRole.USER).multiContent(multiContents).build(); messages.add(userMessage1); ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder() .model("请填写火山方舟模型 ID") .messages(messages) .build(); arkService.createChatCompletion(chatCompletionRequest1).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent())); arkService.shutdownExecutor(); } } \`\`\` `}>); ``` AI MediaKit 会利用视频云的媒体处理流水线执行以下操作： 1. 拉取视频：从公网 URL 或云存储下载原始视频。 2. 智能抽帧：根据您的 `fps` 设置（默认每秒 1 帧）提取视频帧。 3. 序列转换：将视频转换为“时间戳 + 图片”的结构化序列。 4. 模型推理：将转换后的多模态请求发送至火山方舟大模型获取结论。 :::warning 若您的视频文件小于 50 MB，或需要使用 Base64 编码、Files API 等方式传入视频，可直接调用火山方舟 API，详见[火山方舟视频理解文档](https://www.volcengine.com/docs/82379/1895586?lang=zh)。 ::: ## 进阶使用 ### 控制视频理解的精细度和 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` 的成本“熔断”机制，确保总帧数不会超过您的预期。 #### 示例：在请求中设置抽帧参数 ```mixin-react return ( messages = new ArrayList<>(); final List multiContents = new ArrayList<>(); final ChatCompletionContentPart textPart = ChatCompletionContentPart.builder().type("text").text("描述下视频里出现的场景？").build(); multiContents.add(textPart); final ChatCompletionContentPart.ChatCompletionContentPartVideoURL videoURL = new ChatCompletionContentPart.ChatCompletionContentPartVideoURL("https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4", 2.0, 100, 518400); final ChatCompletionContentPart videoPart = ChatCompletionContentPart.builder().type("video_url").videoUrl(videoURL).build(); multiContents.add(videoPart); final ChatMessage userMessage1 = ChatMessage.builder().role(ChatMessageRole.USER).multiContent(multiContents).build(); messages.add(userMessage1); ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder() .model("请填写火山方舟模型 ID") .messages(messages) .build(); arkService.createChatCompletion(chatCompletionRequest1).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent())); arkService.shutdownExecutor(); } } \`\`\` `}>); ``` ### 感知视频时序视频理解可理解视频时间和图像关系信息，如回答事件发生在什么时间点，在哪些时间发生了某事件等和时间相关的信息，详见[视频理解工作原理](/docs/6448/2222229#29ae9f5c)。您可在提示词中加入类似“请给出具体时间点”的要求。示例代码如下： ```mixin-react return ( messages = new ArrayList<>(); final List multiContents = new ArrayList<>(); final ChatCompletionContentPart textPart = ChatCompletionContentPart.builder().type("text").text("裁判什么时间点出现的？").build(); multiContents.add(textPart); final ChatCompletionContentPart.ChatCompletionContentPartVideoURL videoURL = new ChatCompletionContentPart.ChatCompletionContentPartVideoURL("https://ark-project.tos-cn-beijing.volces.com/doc_video/video-understanding.mp4", 5.0); final ChatCompletionContentPart videoPart = ChatCompletionContentPart.builder().type("video_url").videoUrl(videoURL).build(); multiContents.add(videoPart); final ChatMessage userMessage1 = ChatMessage.builder().role(ChatMessageRole.USER).multiContent(multiContents).build(); messages.add(userMessage1); ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder() .model("请填写火山方舟模型 ID") .messages(messages) .build(); arkService.createChatCompletion(chatCompletionRequest1).getChoices().forEach(choice -> System.out.println(choice.getMessage().getContent())); arkService.shutdownExecutor(); } } \`\`\` `}>); ``` 回复预览 ```Plain Text 根据视频描述，裁判在**3.7秒**左右出现。此时，画面中两位拳击手（左为黑T恤红短裤、右为白T恤黑短裤）原本处于对峙状态，随后裁判（穿着黑色西装、戴白手套）站到两人中间，似乎在准备开始比赛或暂停当前回合，观众仍在背景中欢呼。 ``` ### 流式输出流式输出支持内容动态实时呈现，既能够缓解用户等待焦虑，又可以规避复杂任务因长时间推理引发的客户端超时失败问题，保障请求流程顺畅。 ```mixin-react return ( messages = new ArrayList<>(); final List multiContents = new ArrayList<>(); final ChatCompletionContentPart textPart = ChatCompletionContentPart.builder().type("text").text("描述下视频里出现的场景？").build(); multiContents.add(textPart); final ChatCompletionContentPart.ChatCompletionContentPartVideoURL videoURL = new ChatCompletionContentPart.ChatCompletionContentPartVideoURL("https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4", 1.0); final ChatCompletionContentPart videoPart = ChatCompletionContentPart.builder().type("video_url").videoUrl(videoURL).build(); multiContents.add(videoPart); final ChatMessage userMessage1 = ChatMessage.builder().role(ChatMessageRole.USER).multiContent(multiContents).build(); messages.add(userMessage1); ChatCompletionRequest chatCompletionRequest1 = ChatCompletionRequest.builder() .model("请填写火山方舟模型 ID") .messages(messages) .stream(true) .build(); arkService.streamChatCompletion(chatCompletionRequest1) .doOnError(Throwable::printStackTrace) .blockingForEach(System.out::println); arkService.shutdownExecutor(); } } \`\`\` `}>); ``` ## 使用说明 :::tip 处理完视频后，文件会从火山服务器删除。火山不会保留您提交的视频以及文本信息等用户数据来训练模型。 ::: ### 时序信息基于 FPS 的抽帧获取视频帧，再通过时间戳+图像拼接标记时序信息，模型基于该请求中的时序标记和图像内容，实现对视频的完整理解（包括内容变化、动作逻辑、时序关联等）。详细信息见[视频理解工作原理](/docs/6448/2222229#29ae9f5c)。 ### 视频格式说明支持 MP4、FLV、ASF、RM、RMVB、MPEG、MOV、AVI、MPEGTS、M4S、WMV、3GP、TS、MPG、WEBM、MKV、MPE、VOB、DAT、MP4V、M4V、F4V、MXF、QT 等主流视频格式。 :::warning * 视频文件格式变种较多，不能保证所有文件都能被识别，请通过测试验证文件能够被正常识别。 * 对于 HLS 格式视频，当您传入 M3U8 地址进行处理时，如果 M3U8 文件中含有 `EXT-X-MAP` 标签，目前暂不支持处理。 ::: ### 视频文件大小限制使用 URL 方式传入视频，视频文件不能超过 5GB。 ### 不支持音频理解暂不支持对视频文件中的音频信息进行理解。 ### 抽帧策略 AI MediaKit 视频理解服务内置了成本控制机制，默认将单次视频处理的总 Token 消耗限制在 200k 以内，确保任务稳定运行，避免超长视频或高分辨率素材导致上下文窗口溢出或费用失控。抽帧决策遵循以下逻辑： 1. **计算单帧 Token 成本**：AI MediaKit 首先会检查您是否设置了 `max_pixels` 参数。如果视频原始分辨率（`宽 × 高`）超过 `max_pixels` 的限制，系统会先将图片等比缩小，然后再根据缩小后的分辨率，参考 [图片 token 用量估算规则](https://www.volcengine.com/docs/82379/1362931?lang=zh#885d96dc)估算单帧画面的 Token 消耗。 * 默认 `max_pixels`：若不设置，默认为 677,376。 * 最大 `max_pixels`：最大值为 9,031,680，超出部分按最大值计算。 2. **计算预算内最大帧数**：根据第一步算出的“单帧 Token 成本”，系统用总预算（200k Token）计算出在此成本下，最多能处理多少帧图像，这个数量即为 `MaxFrames_budget`。 3. **抽帧方案判定**：系统会综合评判 `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] | |视频帧 |`` |`` |`` | |时间戳 |[1.0 second] |[2.0 second] |[0.5 second] | |视频帧 |`` |`` |`` | |时间戳 |[2.0 second] |[4.0 second] |[1.0 second] | |视频帧 |`` |`` |`` | |时间戳 |[3.0 second] | |[1.5 second] | |视频帧 |`` | |`` | |时间戳 |[4.0 second] | |[2.0 second] | |视频帧 |`` | |`` | |时间戳 |[5.0 second] | |[2.5 second] | |视频帧 |`` | |`` | |时间戳 | | |[3.0 second] | |视频帧 | | |`` | |时间戳 | | |[3.5 second] | |视频帧 | | |`` | |时间戳 | | |[4.0 second] | |视频帧 | | |`` | |时间戳 | | |[4.5 second] | |视频帧 | | |`` | |时间戳 | | |[5.0 second] | |视频帧 | | |`` | | |*共 6 帧* |*共 3 帧* |*共 11 帧* | ### 多图请求等效视频理解请求等效于下面示例的多图理解请求。 ```JSON { "model": "doubao-seed-1-6-251015", "messages": [ { "role": "user", "content": [ { "type":"text", "text":"你觉得这个恐怖吗？" }, { "type":"text", "text":"[0.0 second]" }, { "type":"image_url", "image_url":{ "url":""} }, { "type":"text", "text":"[1.0 second]" }, { "type":"image_url", "image_url":{ "url":""} }, { "type":"text", "text":"[2.0 second]" }, { "type":"image_url", "image_url":{ "url":""} }, { "type":"text", "text":"[3.0 second]" }, { "type":"image_url", "image_url":{ "url":""} }, { "type":"text", "text":"[4.0 second]" }, { "type":"image_url", "image_url":{ "url":""} }, { "type":"text", "text":"[5.0 second]" }, { "type":"image_url", "image_url":{ "url":""} } ] } ] } ```

智能处理