SubmitVideoAnalysisTask - 视频理解-提交异步任务_大模型服务平台百炼(Model Studio)-阿里云帮助中心

阿里云百炼轻应用-提交视频理解离线异步任务。

接口说明

阿里云百炼轻应用-视频理解-提交离线异步任务：区别于在线同步任务接口，可以提交视频理解异步任务，无需等待执行结束，后台异步调度，结果可以通过“获取异步任务状态和结果”接口查询。

默认支持 2 并发，可以通过配置接口（UpdateVideoAnalysisConfig）调整并发到 10（如果业务量大，可以联系客服（或运营等）申请更多并发），并发数等于后台同时运行的任务数，超过并发数的任务会后台排队。

接口调用，支持绝大部分开发语言 SDK 方式接入，openapi 门户可以直接调试和使用，也可以到轻应用-影视传媒视频理解控制台，切换到“API” 页签下查看调用 demo。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
quanmiaolightapp:SubmitVideoAnalysisTask	create	全部资源 ``	无	无

请求语法

POST /{workspaceId}/quanmiao/lightapp/videoAnalysis/submitVideoAnalysisTask HTTP/1.1

请求参数

名称	类型	必填	描述	示例值
workspaceId	string	是	阿里云百炼业务空间唯一标识：获取 workspaceId	llm-xxx
videoUrl	string	是	视频 url	http://xxxx.mp4
videoModelId	string	否	视频 vl 任务模型唯一标识，支持的模型： qwen-vl-max-latest qwen-vl-max qwen-vl-plus-latest qwen-vl-plus	qwen-vl-max-latest
videoModelCustomPromptTemplate	string	否	视频 vl 任务 prompt 模版：必须包含{videoAsrText}变量，{videoAsrText}是视频的 ASR 文本信息，不传默认取页面看到的默认值。	# 角色你是一名视频分析师，擅长对各种视频片段进行理解。 # 任务描述给你一个视频片段的多张关键帧图片，请你完成以下任务。 - 输出每张图片的画面信息，包括人物、物体、动作、文字、字幕、镜头语言等。 - 把每张图片的信息串联起来，生成视频的详细概述，还原该片段的剧情。 # 限制 - 分析范围严格限定于提供的视频子片段，不涉及视频之外的任何推测或背景信息。 - 总结时需严格依据视频内容，不可添加个人臆测或创意性内容。 - 保持对所有视频元素（尤其是文字和字幕）的高保真还原，避免信息遗漏或误解。 # 输入数据 ## 视频片段ASR信息（如果输入为空则忽略ASR信息） {videoAsrText} # 输出格式直接按照任务目标里即可,先输出每张图片的描述，再串联起来输出整个视频片段的剧情。
modelId	string	否	视频总结（文本加工）依赖的大模型唯一标识，如果文本加工阶段想跑多任务，可以走 textProcessTasks 字段，如果传入了 textProcessTasks，则当前字段和当前字段对应的 prompt 模版 id，prompt 模版将不再生效。支持的模型清单：已控制台说明为准 qwen-max-latest qwen-max qwen-plus-latest qwen-plus qwen2.5-7b-instruct-1m deepseek-r1	qwen-max
modelCustomPromptTemplateId	string	否	视频总结依赖的大模型 prompt 模版唯一标识： PlotDetail：剧情详解（默认）； Summary：内容概述； ExtractVideoTag：提取标签； ExplosivePointAnalysis：爆点分析； MultiTask：多类任务；如果 modelCustomPromptTemplate 未传，则会取模版唯一标识对应的默认 prompt，modelCustomPromptTemplate 优先级高于 modelCustomPromptTemplateId。	PlotDetail
modelCustomPromptTemplate	string	否	视频总结依赖的大模型 prompt 模版：必须同时包含{videoAsrText} 和 {videoAnalysisText}变量，{videoAsrText}是视频的 ASR 文本信息，{videoAnalysisText}是视频的各个子镜头的 VL 视觉信息，不传默认取页面看到的默认值。	# 角色你是一个专业的视频标注专员，擅长结合视频镜头信息来分析处理各种视频任务。 # 任务目标请你结合输入数据串联、还原出整个视频的详细剧情。 # 限制 1.如出现语法上错误，或逻辑不通，请直接修改 2.在视频分镜中，如果包含台词，可能会出现说话者与其所说内容不匹配的情况。因此，必须根据剧情的进展，准确判断每段台词的真实说话者 3.如果视频分镜中无台词，请根据视频音频文字为其匹配台词 4.修改后的故事请适当保留视频分镜中对人物、场景的描写 5.帮忙润色一下故事，使其更具逻辑性 6.结合视频分镜中的人物外观特点，如果有外观相近的人物是同一个角色。因此，需要将不同分镜中的人物角色统一。 # 输入数据 ## 资料一：视频分镜信息（视频各镜头的视觉描述信息） {videoAnalysisText} ## 资料二：视频ASR转录信息（未标注出说话者，可能有错误和遗漏，如果没有输入ASR，则忽略此信息） {videoAsrText} # 输出格式直接输出视频剧情，不要输出其他信息。
generateOptions	array	否	视频理解生成任务选项。
	string	否	视频理解生成任务选项：包含的任务，会自动前置执行。 videoAnalysis：视频语言分析（VL）：如果仅传次值，则运行到视频语言分析后就结束了，不再跑后面的文本加工等子任务； videoGenerate：文本加工-视频总结（默认），包含 videoAnalysis； videoTitleGenerate：视频标题生成，包含 videoAnalysis、videoGenerate； videoMindMappingGenerate：视频思维导图生成，包含 videoAnalysis、videoGenerate；	videoGenerate
videoExtraInfo	string	否	自定义扩展文本素材：应用到生成中，需要手动调整 prompt 模版，增加{videoExtraInfo}变量	视频描述了：xx
snapshotInterval	double	否	抽帧间隔：X 秒一帧，取值范围[1, 10]，间隔越大模型能提取到的信息越少，耗时越长，成本越高，默认已是最佳实践，一般无需修改，如果要修改，请根据视频时长来定，建议[1~3]。建议使用：当前字段优先级高于 frameSampleMethod.interval，一般场景可以使用 frameSampleMethod 字段自定义（userdefined）模式下的 interval，区别在于 frameSampleMethod 自定义模式 interval 取值需要在指定的视频时长对应抽帧间隔范围内。	2
splitInterval	integer	否	视频分镜最小间隔：单位秒，取值范围[1, 150]，默认根据视频长度取推荐值	10
language	string	否	语言，可传参数 chinese：中文（默认） french：法语 english：英语 japanese：日语 chineseEnglishFreely：中英文自由说	chinese
frameSampleMethod	object	否	抽帧方式
methodName	string	否	抽帧类型，可传参数包括 fast：快速/更低成本 standard：标准（默认） userdefined：自定义	standard
interval	double	否	抽帧间隔：单位秒，仅在 userdefined 模式下有效	2
pixel	integer	否	抽帧像素：每一帧最大边像素，仅在 userdefined 模式下有效，取值范围是 300 到 768	768
videoRoles	array<object>	否	识别视频中的人物身份列表
	object	否	识别视频中的人物身份
roleName	string	否	人物名称	张三
roleInfo	string	否	人物信息描述	张三是一个男生
urls	array	否	人物头像地址
	string	否	人物头像地址	http://xxx
textProcessTasks	array<object>	否	视频总结(文本加工)任务列表:最多支持 3 个
	object	否	视频总结(文本加工)任务
modelId	string	否	视频总结依赖的大模型唯一标识，支持的模型 qwen-max-latest qwen-max qwen-plus-latest qwen-plus qwen2.5-7b-instruct-1m deepseek-r1	qwen-max-latest
modelCustomPromptTemplate	string	否	视频总结依赖的大模型 prompt 模版：必须同时包含{videoAsrText} 和 {videoAnalysisText}变量，{videoAsrText}是视频的 ASR 文本信息，{videoAnalysisText}是视频的各个子镜头的 VL 视觉信息，不传默认取页面看到的默认值。	xx
modelCustomPromptTemplateId	string	否	视频总结依赖的大模型 prompt 模版唯一标识： PlotDetail：剧情详解（默认）； Summary：内容概述； ExtractVideoTag：提取标签； ExplosivePointAnalysis：爆点分析； MultiTask：多类任务；如果 modelCustomPromptTemplate 未传，则会取模版唯一标识对应的默认 prompt，modelCustomPromptTemplate 优先级高于 modelCustomPromptTemplateId。	PlotDetail
faceIdentitySimilarityMinScore	float	否	人物识别相似度阈值：0~1	0.7
videoShotFaceIdentityCount	integer	否	人物匹配时，单镜头(分镜)，参与匹配的抽帧（图片）数量：[1~5]	2
deduplicationId	string	否	排重字段：可以根据业务需要和业务场景定义自己的业务唯一标识，当前字段重复的数据，系统会保证至少 72h 内不允许重复提交	1
excludeGenerateOptions	array	否	排除的生成步骤： videoCaption：视频语音识别
	string	否
videoCaptionInfo	object	否	字幕（asr）信息
videoCaptions	array<object>	否	字幕（ASR）内容，和 videoCaptionsFIleUrl 二选一
	object	否	字幕（asr）内容
startTime	long	否	当前句子开始时间：毫秒	1000
endTime	long	否	当前句子结束时间：毫秒	10000
text	string	否	内容	你好
speaker	string	否	角色	张三
videoCaptionFileUrl	string	否	视频字幕（ASR）文件	oss:// \| http://

返回参数

名称	类型	描述	示例值
	object	Schema of Response
requestId	string	请求唯一标识	085BE2D2-BB7E-59A6-B688-F2CB32124E7F
success	boolean	是否成功：true 成功，false 失败	True
code	string	状态码	xx
message	string	错误说明	success
httpStatusCode	integer	http 状态码	200
data	object	结果
taskId	string	任务唯一标识	3feb69ed02d9b1a17d0f1a942675d300

示例

正常返回示例

JSON格式

{
  "requestId": "085BE2D2-BB7E-59A6-B688-F2CB32124E7F",
  "success": true,
  "code": "xx",
  "message": "success",
  "httpStatusCode": 200,
  "data": {
    "taskId": "3feb69ed02d9b1a17d0f1a942675d300"
  }
}

错误码

HTTP status code	错误码	错误信息	描述
403	NoPermission	You are not authorized to perform this action , Please check the assignment of the workspaceId.	请检查workspaceId的赋值

访问错误中心查看更多错误码。