本文为您详细介绍如何调用 StartExecution 接口提交异步的长视频理解任务。该功能提供 Vision（深度语义分析）与 VideoUnderstanding（分析+场景切分）两种模式，依托豆包大模型能力，对最长 2 小时的视频进行多模态深度理解，生成视频描述、摘要、标签或结构化切片分析，助力媒资智能化运营。详细功能介绍和使用流程请见长视频理解开发指南。

使用说明

调用准备：在调用本接口前，建议您先阅读如何调用 OpenAPI 文档，以了解 OpenAPI 的通用调用流程，包括在线调试、获取 curl 命令、请求签名等基础操作。

任务模式选择指引：您可以根据是否需要“场景切分”结果来选择具体的任务类型：

Vision：侧重于通过 VLM+LLM 模式对视频进行全局总结、标签提取和细节描述。适用于视频内容大纲提取、智能打标、自动化文案生成。

VideoUnderstanding：在进行视频理解的同时，支持同步输出场景切分（Segmentation）结果。适用于视频拆条、按场景生成摘要、视频点位分析。

结果获取方式：任务提交后，系统将在后台进行异步处理。您可以通过以下任一方式获取任务的最终结果：

主动查询：调用 GetExecution，传入 RunId 来轮询任务状态。若任务成功：

Vision 的结果位于 Output.Task.Vision.Content。

VideoUnderstanding 的结果位于 Output.Task.VideoUnderstanding（包含 Segments 数组或全局 Content）。

事件通知：配置事件通知并订阅媒体处理任务执行完成事件，任务完成后系统将主动向您配置的地址发送回调通知。

注意事项

计费说明：提交任务会产生视频 AI 费用，具体参见视频 AI 应用计费。

QPS 限制：本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。

请求说明

请求方式：POST

请求地址：https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

Action String 必选示例值：StartExecution

接口名称。当前 API 的名称为 StartExecution。

Version String 必选示例值：2025-01-01

接口版本。当前 API 的版本为 2025-01-01。

Body

Input Object 可选示例值：-

输入文件信息。

Type String 必选示例值：Vid

输入文件类型。取值如下：

Vid：Vid 模式。此模式下，您还需设置 Vid 参数。

DirectUrl：DirectUrl 模式。此模式下，您还需设置 DirectUrl 参数。

Vid String 可选示例值：v0ccfeg7007acsg***fog65ubr7niqng

待处理视频的 Vid。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其 Vid。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

DirectUrl Object 可选示例值：-

Operation Object 必选示例值：-

媒体处理操作配置。

Type String 必选示例值：Task

处理类型。取值如下：

Task：单任务。

Task Object 可选示例值：-

单任务配置。当 Type 为 Task 时需要设置此参数。

Type String 必选示例值：Vision

任务类型：

Vision: 长视频理解任务。

VideoUnderstanding：长视频理解任务（支持在视频理解时进行场景切分）。

Vision Object 可选示例值：-

视频理解任务配置。当 Type 为 Vision时需要设置此参数。

Prompt String 必选示例值：\n# 角色\n你是一个视频理解的专家，擅长理解和分析视频。\n\n# 任务\n输入的内容是从爆火网络视频中总结的视频分段描述文本和视频音频转译的文本，请根据输入的内容理解视频，并详细描述一下视频的内容.\n\n# 视频分段描述文本\n{{PLACEHOLDER_VIDEO_CLIP_RESULT}}\n\n# 视频转音频文本\n{{PLACEHOLDER_ASR_RESULT}}

大模型提示词。使用 UTF-8 编码。长度不可超过 30000 个字符。根据 Model 参数所配置的视频理解模式，提示词中需包含相应占位符：

VLM + LLM 模式：需包含以下两个占位符

{{PLACEHOLDER_ASR_RESULT}}：控制是否启用 ASR（语音识别）。

{{PLACEHOLDER_VIDEO_CLIP_RESULT}}：控制是否进行视频切片。

仅 VLM 或仅 LLM 模式：只需包含 {{PLACEHOLDER_ASR_RESULT}}占位符。

Model Object 必选示例值：-

大模型配置。您可通过此参数配置对视频的理解模式。支持以下三种模式：

纯视觉理解（仅 VLM）：适用于需要分析视频画面内容的场景（如不超过 10 分钟的短视频）。会进行视频截图，建议截图分辨率设为 240p 以获得更多截图。推荐使用支持 128k 及以上上下文的模型（如 doubao-seed-1.6-thinking）。

纯音频理解（仅LLM）：适用于无需理解视频画面内容的场景（如演讲视频等）。

多模态理解（VLM+LLM）：适用于长视频理解（最长支持 2 小时）。会将长视频切分成多个片段，使用 VLM 分别理解每个片段，最后用 LLM 汇总各片段理解结果。

DoubaoVisionEndpoint String 可选示例值：ep-202412***75335-cg2p7

豆包 VLM (Vision Language Model) 模型的推理接入点 ID。具体请见开通豆包大模型并获取 Endpoint ID。

注意

DoubaoVisionEndpoint 和 DoubaoTextEndpoint二选一必填。

AsrAppId String 必选示例值：3500***054

语音识别 (ASR) 产品的 APP ID。具体请见开通大模型流式语音识别服务并获取 APP ID.

AsrAppType String 必选示例值：volc.bigasr.sauc.duration

语音识别 (ASR) 产品中流式语音识别大模型的类型，需与您开通的服务类型保持一致。取值如下：

volc.bigasr.sauc.duration: 小时版

volc.bigasr.sauc.concurrent: 并发版

DoubaoTextEndpoint String 可选示例值：ep-202412***75335-cg2p7

豆包 LLM (Large Language Model) 模型的推理接入点 ID。具体请见开通豆包大模型并获取 Endpoint ID。

注意

DoubaoVisionEndpoint 和 DoubaoTextEndpoint二选一必填。

Segment Object 可选示例值：-

视频分段理解配置。用于指定视频理解任务的起始和结束时间。若不设置 Start，则默认从视频开头开始；若不设置 End，则默认到视频结尾结束。End 要大于 Start。

Start Double 可选示例值：100

起始时间，单位为秒。

End Double 可选示例值：200

结束时间，单位为秒。

SnapshotParam Object 可选示例值：-

截图策略配置。视频理解处理过程中会对视频进行截图。默认截图策略为均匀时间间隔截图最多 50 张。若您需要更改截图策略，可传入此参数。

Resolution String 必选示例值：720p

视频截图的分辨率，取值如下：

240p

360p

480p

720p

1080p

Fps Double 必选示例值：1

每秒截取的帧数。

Area Object 可选示例值：-

截图区域配置。

TopLeftX Double 可选示例值：0

框选区域左上角相对于视频左上角在X轴上的偏移比例，取值范围为[0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

TopLeftY Double 可选示例值：0

框选区域左上角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

BottomRightX Double 可选示例值：0

框选区域右下角相对于视频左上角在 X 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频左边缘对齐），1 表示完全偏移（与视频右边缘对齐）。

BottomRightY Double 可选示例值：0

框选区域右下角相对于视频左上角在 Y 轴上的偏移比例，取值范围为 [0,1]，其中 0 表示无偏移（与视频上边缘对齐），1 表示完全偏移（与视频下边缘对齐）。

NeedAsrSpeaker Boolean 可选示例值：true

是否在 ASR（语音识别）结果中包含说话人信息并用于大模型的推理。默认值为 false。

true：包含说话人信息并用于推理，需要 AsrAppType 为录音识别大模型 volc.bigasr.auc_turbo 才生效；

false：不包含说话人信息。

ResponseFormatType String 可选示例值：json_object

指定视频理解结果的输出格式。支持的取值如下：

""：默认值，不产生任何效果，大模型输出的格式由 Prompt 中指定。

json_object：大模型会参考 Prompt 中指定的 JSON 格式稳定输出准确的 JSON 格式。

VideoUnderstanding Object 可选示例值：-

视频理解任务配置。当 Type 为 VideoUnderstanding 时需要设置此参数。

Prompt String 必选示例值：-

WithSegment Boolean 可选示例值：true

Segment Object 可选示例值：-

Model Object 可选示例值：-

Control Object 可选示例值：-

任务控制配置。

ClientToken String 可选示例值：QqS3o5L4BLFCDxGZ&b

用户请求凭证，用于区分不同请求。大小写敏感，不超过 64 个 ASCII 码可打印字符。默认情况下，视频点播转码服务在接收到触发工作流请求后，会执行幂等行为。这意味着，如果判定当前请求与之前发送的请求相同，则不会重复执行该请求。关于幂等行为、目的和条件，请参考工作流幂等说明。若您希望跳过幂等行为，例如修改了某一工作流所绑定的媒体处理模板中的配置，想要对同一个 Vid 重新执行相同的工作流，则可以设置此参数。

CallbackArgs String 可选示例值：Example

自定义字段，将在媒体处理任务执行完成事件中透传返回。字段长度最大为 512 字节。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

RunId String 示例值：hb:c5cacd4946bd***a5fd9f74159b03ae8

媒体处理任务执行 ID。

请求示例：多模态视频理解

通过 Vid 提交多模态（VLM+LLM）视频理解任务。

错误码

本接口无特有的错误码。更多信息请见公共错误码。

服务端 SDK

视频点播为 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API。本接口仅 VOD SDK 2.0 支持，详见 V2.0 SDK 介绍与迁移说明。