视觉大模型可理解视频中的视觉信息，完成如描述其中的物体、分析动作逻辑等视觉相关任务，可用于自动化视频内容审核、智能监控分析等，大幅节省人工成本，适用于智能安防、体育赛事分析、媒体内容管理等领域。这篇教程帮助您通过 API 完成含视频输入的各类任务。 :::tip 方舟平台的新用户？获取 API Key 及开通模型等准备工作，请参见 [快速入门](/docs/82379/1399008)。 ::: # 支持模型请参见[视觉理解能力](/docs/82379/1330310#ff5ef604)。 # API 接口 * [Responses API](https://www.volcengine.com/docs/82379/1569618)：支持视频作为输入进行分析。支持 File ID 方式进行视频理解，使用方式参见[Files API 上传（推荐）](/docs/82379/1895586#35d3ebc5)。 * [Chat API](https://www.volcengine.com/docs/82379/1494384)：支持视频作为输入进行分析。 # 视频传入方式支持的视频文件传入方式如下： * 本地文件上传： * [Files API 上传（推荐）](/docs/82379/1895586#35d3ebc5)：直接传入本地文件，视频文件大小不能超过 512 MB，适用于在多个请求中重复使用文件的场景。 * [Base64 编码传入](/docs/82379/1895586#22314028)：适用于文件体积较小的场景，视频文件小于 50 MB，请求体不能超过 64 MB。 * [视频 URL 传入](/docs/82379/1895586#8e3a48ed)：适用于文件已存在公网可访问 URL 的场景，视频文件大小不能超过 50 MB。 ## 本地文件上传 ### Files API 上传（推荐）建议优先使用 Files API 上传本地文件，不仅可以支持最大 512MB 文件的处理，还可以避免请求时重新上传内容，减少预处理导致的时延，同时可在多次请求中重复使用，节省公网下载时延。（当前Responses API支持该方式。） > * 该方式上传的文件默认存储 7 天，存储有效期取值范围为1\-30天。 > * 如果需要实时获取分析内容，或者要规避复杂任务引发的客户端超时失败问题，可采用流式输出的方式，具体示例见[流式输出](/docs/82379/1895586#5cfd1f60)。 ```mixin-react return ( ); ``` ### Base64 编码传入将本地文件转换为 Base64 编码字符串，然后提交给大模型。该方式适用于视频文件体积较小的情况，文件不能超过 50 MB，请求体不能超过 64 MB。（Responses API 和 Chat API 都支持该方式。） :::warning 将视频文件转换为Base64编码字符串，然后遵循`data:{mime_type};base64,{base64_data}`格式拼接，传入模型。 * `{mime_type}`：文件的媒体类型，需要与文件格式mime_type对应。支持的视频格式详细见[视频格式说明](/docs/82379/1895586#ea7689ca)。 * `{base64_data}`：文件经过Base64编码后的字符串。 ::: * 使用 Responses API 的示例代码如下： ```mixin-react return ( ); ``` * 使用 Chat API 的示例代码如下： ```mixin-react return ( ;base64,{base64_video}" }, }, { "type": "text", "text": "What's in the video?", }, ], } ], ) print(completion.choices[0]) \`\`\` `}> messagesForReqList = new ArrayList<>(); // 本地视频路径（替换为实际路径） String videoPath = "demo.mp4"; // 生成Base64数据URL String base64Data = "data:video/mp4;base64," + encodeVideo(videoPath); // 构建消息内容（修复内容部分构建方式） List contentParts = new ArrayList<>(); // 图片部分使用builder模式 contentParts.add(ChatCompletionContentPart.builder() .type("video_url") .videoUrl(new ChatCompletionContentPartVideoURL(base64Data, 2)) .build()); // 文本部分使用builder模式 contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("What's in the video?") .build()); // 创建消息 messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ## 视频 URL 传入如果视频文件已存在公网可访问URL，可以在请求中直接填入视频文件的公网URL，文件不能超过50 MB。（Responses API 和 Chat API 都支持该方式。） * 使用 Responses API 的示例代码如下： ```mixin-react return ( ); ``` * 使用 Chat API 的示例代码如下：（可参见[控制视频理解的精细度](/docs/82379/1895586#bf4d9224)） ```mixin-react return ( ); ``` # 使用场景 ## 控制视频理解的精细度您可通过 **fps** 字段，控制从视频中抽取图像的频率，默认为1，即每秒从视频中抽取一帧图像，输入给模型进行视觉理解。可通过 **fps** 字段，控制模型对于视频中图像变化的敏感度。 * 当视频画面变化剧烈或需关注画面变化，如计算视频中角色动作次数，可调高 **fps** 设置（最高 `5`），防止抽帧频率低导致误判。 * 当视频画面变化不频繁或无需关注画面变化，如画面中人数，可调低 **fps** （最低`0.2`），可提升处理速度，节省 token 用量。示例代码如下： ```mixin-react return ( messagesForReqList = new ArrayList<>(); // 构建消息内容 List contentParts = new ArrayList<>(); contentParts.add(ChatCompletionContentPart.builder() .type("video_url") .videoUrl(new ChatCompletionContentPartVideoURL( "https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4",2)) .build()); contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("What's in the video?") .build()); // 创建消息 messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ## 感知视频时序视频理解可理解视频时间和图像关系信息，如回答事件发生什么时间点，在哪些时间发生了某事件等和时间相关的信息，原理见 [视频理解工作原理](/docs/82379/1895586#b5f696d3)。下面是简单示例代码 ```mixin-react return ( messagesForReqList = new ArrayList<>(); // 构建消息内容 List contentParts = new ArrayList<>(); contentParts.add(ChatCompletionContentPart.builder() .type("video_url") .videoUrl(new ChatCompletionContentPartVideoURL( "https://ark-project.tos-cn-beijing.volces.com/doc_video/video-understanding.mp4",5)) .build()); contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("裁判什么时间点出现的？") .build()); // 创建消息 messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` 回复预览 ```Plain 根据视频描述，裁判在**3.7秒**左右出现。此时，画面中两位拳击手（左为黑T恤红短裤、右为白T恤黑短裤）原本处于对峙状态，随后裁判（穿着黑色西装、戴白手套）站到两人中间，似乎在准备开始比赛或暂停当前回合，观众仍在背景中欢呼。 ``` ## 流式输出流式输出支持内容动态实时呈现，既能够缓解用户等待焦虑，又可以规避复杂任务因长时间推理引发的客户端超时失败问题，保障请求流程顺畅。 ```mixin-react return ( { if (event instanceof ReasoningSummaryTextDeltaEvent) { System.out.print(((ReasoningSummaryTextDeltaEvent) event).getDelta()); } if (event instanceof OutputItemAddedEvent) { System.out.println("\\nOutputItem " + (((OutputItemAddedEvent) event).getItem().getType()) + " Start: "); } if (event instanceof OutputTextDeltaEvent) { System.out.print(((OutputTextDeltaEvent) event).getDelta()); } if (event instanceof OutputTextDoneEvent) { System.out.println("\\nOutputText End."); } if (event instanceof OutputItemDoneEvent) { System.out.println("\\nOutputItem " + ((OutputItemDoneEvent) event).getItem().getType() + " End."); } if (event instanceof FunctionCallArgumentsDoneEvent) { System.out.println("\\nFunctionCall Arguments: " + ((FunctionCallArgumentsDoneEvent) event).getArguments()); } if (event instanceof ResponseCompletedEvent) { System.out.println("\\nResponse Completed. Usage = " + ((ResponseCompletedEvent) event).getResponse().getUsage()); } }); service.shutdownExecutor(); } } \`\`\` `}> # 使用说明 :::tip 处理完图片/视频后，文件会从方舟服务器删除。方舟不会保留您提交的图片、视频以及文本信息等用户数据来训练模型。 ::: ## 时序信息基于 FPS 的抽帧获取视频关键帧，再通过`时间戳+图像`拼接标记时序信息，模型基于该请求中的时序标记和图像内容，实现对视频的完整理解（包括内容变化、动作逻辑、时序关联等）。详细原理见 [视频理解工作原理](/docs/82379/1895586#b5f696d3)。 ## 视频格式说明 |**视频格式** |**文件扩展名** |**内容格式** **Content Type** | |---|---|---| |MP4 |.mp4 |`video/mp4` | |AVI |.avi |`video/avi` | |MOV |.mov |* url传入视频：对象存储请设置 Content Type 为`video/quicktime`|\ | | |* base64编码：请使用 `video/mov`，即`data:video/mov;base64,` | > 视频文件格式变种较多，不能保证所有文件都能被识别，请通过测试验证文件能够被正常识别。 :::tip * 常见问题及解决方案参见[支持 TS 格式的视频文件吗？](/docs/82379/1359411#85251eec) * 上传视频至对象存储时设置，详情请参见[文档](https://www.volcengine.com/docs/6349/145523#%E8%AE%BE%E7%BD%AE%E6%96%87%E4%BB%B6%E5%85%83%E6%95%B0%E6%8D%AE)。 * 传入 Base64 编码时使用：[Base64 编码输入](/docs/82379/1895586#f6222fec)。 * 视频格式需小写。 ::: ## 视频文件容量使用 URL 方式传入视频，视频文件不能超过 50MB。使用 Base64 编码传入视频，视频文件不能超过 50MB，请求体不能超过 64MB。使用 Files API 上传视频，视频文件不能超过 512 MB。 ## 不支持音频理解暂不支持对视频文件中的音频信息进行理解。 ## 抽帧策略用量说明：单视频最大 token 用量为 80k，单次请求视频最大 token 量还受模型的最大上下文窗口以及最大输入长度（当启用深度思考模式）限制，超出则需调整传入视频数量或视频长度。基本概念： * 帧图像：某个时刻的视频画面，本文特指输入给模型的帧图像 * 帧图像张数：视频时长 \* **fps** 方舟会根据帧图像张数，对帧图像进行压缩，以平衡视频的理解精度和 token 用量。不同模型的抽帧策略不同，具体如下： |抽帧策略 |doubao\-seed\-1.8 之前的模型 |doubao\-seed\-1.8 模型、doubao\-seed\-2.0 模型 | |---|---|---| |单帧最大 tokens |支持 128、160、256、384、512、640 离散 tokens 值。 |* doubao\-seed\-1.8 模型：支持 64、128、192、256、320、384 离散 tokens 值。|\ | | |* doubao\-seed\-2.0 模型：支持 tokens 在 [64, 384] 区间内连续动态调整。 | |单帧对应的max_pixels |单帧最大 tokens \* 28 \* 28|单帧最大 tokens \* 42 \* 42|\ | |[10w, 50w] |[11w, 67w] | |抽帧数 |[16帧, 640帧]|[16帧, 1280帧]|\ | |```Bash|```Bash|\ | |# 最大抽帧数|# 最大抽帧数|\ | |80×1024 token ÷ 128 token/帧 = 640 帧|80×1024 token ÷ 64 token/帧 = 1280 帧|\ | |```|```|\ | | | | |抽帧方案 |:::tip||\ | || |\ | |* 建议评估输出效果，按需调整fps字段配置或视频时长。| |\ | |* 如果视频二进制数据中未包含帧数编码信息，会按 fps 均匀抽帧。单次请求视频最大 Token 量如果超过模型最大输入长度则会报错；未超过则不报错，但视频输入的 token 可能会超过 80k。| |\ | || |\ | |:::| | |^^|* fps 过高或视频长度过长：处理的帧图像数量超出640帧，则按帧图像128tokens，时间间隔`视频时长/640`，均匀抽取640帧。|* fps 过高或视频长度过长：处理的帧图像数量超出1280帧，则按帧图像64tokens，时间间隔 `视频时长/1280`，均匀抽取1280帧。|\ | |* fps 过小或视频长度过短：处理的帧图像数量不足16帧时抽取方案如下：|* fps 过小或视频长度过短：处理的帧图像数量不足16帧时抽取方案如下：|\ | | * 视频总帧数 \>= 16帧，均匀抽取16帧。| * 视频总帧数 \>= 16帧，均匀抽取16帧。|\ | | * 视频总帧数 < 16帧，抽取视频所有帧。 | * 视频总帧数 < 16帧，抽取视频所有帧。 | # 视频理解工作原理视频处理的核心方式为 “帧与时间戳的结构化拼接”，具体规则如下： * 对视频抽帧得到的每帧图像，在其前插入时间戳文本，格式为 `[<时间戳> 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帧* | ## 多图请求等效视频理解请求等效于下面示例的多图理解请求。 ```Plain { "model": "doubao-seed-2-0-lite-260215", "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":""} } ] } ] } ```

火山方舟