帮你快速理解、总结文档立即下载
文档中心>数据万象>API 文档>AI 内容识别>视觉理解（大模型）>视频分析

视频分析

最近更新时间：2026-08-25 16:48:03
我的收藏

本页目录：

接口描述

本接口基于大模型多模态能力，提供通用视频分析功能，支持通过 POST 请求对视频进行内容理解与分析。
您可以选择两种分析方式：使用预设模板获取视频的整体描述与结构化标签，或通过自定义指令让模型按您的业务需求输出分析结论。典型应用包括视频内容审核辅助、视频摘要生成、关键场景识别、媒资打标与商品视频理解等。

授权说明

通过子账号使用本接口时，需在授权策略的 action 中添加 ci:CreateMediaAnalysisJob 权限。数据万象支持的所有操作接口详见 CI action。

服务开通

使用该功能需提前 绑定存储桶，开通数据万象服务。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。

费用说明

该接口为付费服务，产生的费用将由数据万象收取，按本次分析的视频帧数计费，视频帧数默认为1秒1帧（fps = 1），例如一段10秒的视频，则默认抽取 10 帧，计费项与图片分析为同一个计费项，详细计费说明可参见 内容识别费用。

使用限制

使用该接口时，请先确认相关 使用限制。

请求

请求示例

POST /?ci-process=AIMediaAnalysis HTTP/1.1
Host: <BucketName-APPID>.ci.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
Content-Length: <length>
Content-Type: application/xml

<Request>
    <Input>
        <Message>
            <Content>
                <Part>
                    <Type>Video</Type>
                    <ObjectKey>sample/video.mp4</ObjectKey>
                    <Fps>1</Fps>
                </Part>
                <Part>
                    <Type>Text</Type>
                    <Text>请描述视频中出现的主要场景和人物活动。</Text>
                </Part>
            </Content>
        </Message>
    </Input>
    <Conf>
        <Type>Custom</Type>
    </Conf>
</Request>
说明：
调用本接口需携带签名，可通过 HTTP 请求头 Authorization 携带签名鉴权信息，具体设置请参见 请求签名。

请求头

此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。

请求体

请求体为 XML 格式，具体节点描述如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Request
无
通用视频分析的请求配置。
Container
是
Container 节点 Request 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Input
Request
需要分析的输入内容，包含 Message 消息容器。请求中必须包含且仅包含一个视频类型的 Part。
Container
是
Conf
Request
视频分析的配置项。
Container
是
Container 节点 Input 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Message
Request.Input
消息容器，固定为单条。
Container
是
Container 节点 Message 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Content
Request.Input.Message
内容容器，由若干 Part 组成。
Container
是
Container 节点 Content 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Part
Request.Input.Message.Content
多模态内容片段，可重复多个，按出现顺序组装为大模型输入。需包含且仅包含 1 个 Video 类型 Part，可包含多个 Text 类型 Part 。
Container 数组
是
Container 节点 Part 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Type
Request.Input.Message.Content.Part
内容类型，取值：
Video：视频类型，需通过 ObjectKey 或 Url 指定视频来源，并可配置抽帧参数
Text：文本类型，通过 Text 字段传入文本内容。
String
是
ObjectKey
Request.Input.Message.Content.Part
存储在 COS 存储桶中的媒体对象键，例如目录 sample 下的文件 video.mp4，则 ObjectKey 为 sample/video.mp4。仅在 Type 为 Video 时有效，与 Url 节点必须二选一填入。
String
否
Url
Request.Input.Message.Content.Part
公网可访问的媒体链接地址，例如 http://a-1250000.cos.ap-shanghai.myqcloud.com/video.mp4。仅在 Type 为 Video 时有效，与 ObjectKey 节点必须二选一填入。
String
否
Text
Request.Input.Message.Content.Part
文本内容，仅在 Type 为 Text 时有效。长度限制为 2048 字符。可用于传入分析指令（Custom 模式下作为 Prompt）或上下文信息，不填时则由大模型自行分析视频内容。
String
否
Fps
Request.Input.Message.Content.Part
视频抽帧帧率，取值范围0.1 ~ 5，表示每秒抽取的帧数，例如1表示每秒抽取1帧，0.5 表示每2秒抽取1帧。
默认值：1
Float
否
说明：
ObjectKey 和 Url 只能选择其中一种，且必须传入一种，同时传入时优先处理 ObjectKey。
通过 ObjectKey 进行分析为内网操作，不会产生额外的外网流量；通过 Url 进行分析会产生视频所在源站对应的外网流量。
Container 节点 Conf 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
是否必选
Type
Request.Conf
分析类型，取值：
Description：对视频帧序列进行联合分析，返回一段视频内容描述和若干组视频标签。
Custom：将视频帧序列与用户通过 Part 传入的文本一起发送给大模型，输出联合理解结果。
默认值：Description
String
否
TemplateName
Request.Conf
视频分析模板，仅在 Type 为 Description 时有效。目前支持一种预设模板：
FTM：指影视传媒场景，返回一段视频描述加若干组影视传媒行业的 category 标签，例如电视剧
String
否

响应

响应头

此接口返回公共响应头部，详情请参见 公共响应头部 文档。

响应体

该响应体返回为 application/xml 数据。

响应体示例

示例一：Description 模式响应
<Response>
    <Code>0</Code>
    <Message>OK</Message>
    <State>Success</State>
    <AnalysisResult>
        <Type>Description</Type>
        <DescriptionResult>
            <Description>视频为一段影视片段：室内对话场景，两名角色在客厅交谈，机位以中景为主，穿插近景特写，整体色调偏暖，节奏舒缓。</Description>
            <LabelDetail>
                <LabelInfos>
                    <ConfidenceLevel>high</ConfidenceLevel>
                    <LabelInfo>
                        <LabelName>category</LabelName>
                        <LabelValue>影视</LabelValue>
                    </LabelInfo>
                </LabelInfos>
            </LabelDetail>
        </DescriptionResult>
        <MediaInfo>
            <Duration>45.6</Duration>
            <Fps>1</Fps>
            <BilledFrameCount>46</BilledFrameCount>
        </MediaInfo>
        <TemplateName>FTM</TemplateName>
    </AnalysisResult>
</Response>
示例二：Custom 模式响应
<Response>
    <Code>0</Code>
    <Message>OK</Message>
    <State>Success</State>
    <AnalysisResult>
        <Type>Custom</Type>
        <CustomResult>
            <CustomOutput>视频中共出现 2 个主要人物：一名穿蓝色工服的男性（全程出现）和一名穿红色外套的女性（在第 30 秒左右进入画面）。主要活动为货物搬运，未发现异常行为。</CustomOutput>
        </CustomResult>
        <MediaInfo>
            <Duration>62.0</Duration>
            <Fps>0.5</Fps>
            <BilledFrameCount>31</BilledFrameCount>
        </MediaInfo>
    </AnalysisResult>
</Response>

响应体参数说明

具体节点描述如下：
节点名称（关键字）
父节点
描述
类型
Response
无
通用视频分析返回的响应内容。
Container
Container 节点 Response 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
Code
Response
错误码，成功时为 0，失败时返回具体错误码。
String
Message
Response
错误描述，成功时为 OK。
String
State
Response
分析状态，取值：Success（成功）、Failed（失败）。
String
AnalysisResult
Response
分析结果容器，分析成功时返回。
Container
Container 节点 AnalysisResult 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
Type
Response.AnalysisResult
分析类型，取值：Description、Custom。
String
DescriptionResult
Response.AnalysisResult
视频综合描述分析结果，包含描述和标签，当 Type 为 Description 时返回。
Container
CustomResult
Response.AnalysisResult
自定义模式的分析结果，当 Type 为 Custom 时返回。
Container
MediaInfo
Response.AnalysisResult
媒体处理信息，回显本次视频信息与检测帧数。
Container
Container 节点 DescriptionResult 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
Description
Response.AnalysisResult.DescriptionResult
视频的整体描述内容。
String
LabelDetail
Response.AnalysisResult.DescriptionResult
识别到的标签结果容器，可包含多组 LabelInfos。仅当大模型成功输出有效标签时返回；若模型未输出标签（如视频内容无法识别、内容不匹配等场景）或过滤后无有效标签，该字段缺失。
Container
Container 节点 LabelDetail 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
LabelInfos
Response.AnalysisResult.DescriptionResult.LabelDetail
识别到的标签信息容器，每一组 LabelInfos 代表一个识别维度，对应一个置信度，包含多个 LabelInfo。
Container 数组
Container 节点 LabelInfos 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
ConfidenceLevel
Response.AnalysisResult.DescriptionResult.LabelDetail.LabelInfos
标签置信度，值以模型返回的为准。预设场景下默认为 high、medium、low 三个等级，每组 LabelInfos 对应一个置信度。
String
LabelInfo
Response.AnalysisResult.DescriptionResult.LabelDetail.LabelInfos
标签信息子节点，每个 LabelInfo 包含一对标签：标签名称 LabelName 和标签值 LabelValue。
Container 数组
Container 节点 LabelInfo 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
LabelName
Response.AnalysisResult.DescriptionResult.LabelDetail.LabelInfos.LabelInfo
识别出的标签名称。FTM 模板固定为：category。
String
LabelValue
Response.AnalysisResult.DescriptionResult.LabelDetail.LabelInfos.LabelInfo
识别出的标签名称对应的标签值，例如：美食。
String
Container 节点 CustomResult 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
CustomOutput
Response.AnalysisResult.CustomResult
大模型输出结果。
String
Container 节点 MediaInfo 的具体内容如下：
节点名称（关键字）
父节点
描述
类型
Duration
Response.AnalysisResult.MediaInfo
视频时长，单位为秒。
Float
Fps
Response.AnalysisResult.MediaInfo
本次请求设置的抽帧帧率。
Float
BilledFrameCount
Response.AnalysisResult.MediaInfo
本次检测的实际帧数。
Integer

使用案例

案例一：Description 模式（影视传媒场景标签）

传入一段影视视频，使用 FTM 预设模板进行标签分析。

请求

POST /?ci-process=AIMediaAnalysis HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=AKID****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff905****
Host: examplebucket-1250000000.ci.ap-nanjing.myqcloud.com
Content-Length: 420
Content-Type: application/xml

<Request>
    <Input>
        <Message>
            <Content>
                <Part>
                    <Type>Video</Type>
                    <ObjectKey>media/drama_clip.mp4</ObjectKey>
                    <Fps>1</Fps>
                </Part>
            </Content>
        </Message>
    </Input>
    <Conf>
        <Type>Description</Type>
        <TemplateName>FTM</TemplateName>
    </Conf>
</Request>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1280
Connection: keep-alive
Date: Mon, 28 May 2026 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<Response>
    <Code>0</Code>
    <Message>OK</Message>
    <State>Success</State>
    <AnalysisResult>
        <Type>Description</Type>
        <DescriptionResult>
            <Description>视频为一段影视片段：室内对话场景，两名角色在客厅交谈，机位以中景为主，穿插近景特写，整体色调偏暖，节奏舒缓。</Description>
            <LabelDetail>
                <LabelInfos>
                    <ConfidenceLevel>high</ConfidenceLevel>
                    <LabelInfo>
                        <LabelName>category</LabelName>
                        <LabelValue>影视</LabelValue>
                    </LabelInfo>
                </LabelInfos>
            </LabelDetail>
        </DescriptionResult>
        <MediaInfo>
            <Duration>45.6</Duration>
            <Fps>1</Fps>
            <BilledFrameCount>46</BilledFrameCount>
        </MediaInfo>
        <TemplateName>FTM</TemplateName>
    </AnalysisResult>
</Response>

案例二：Custom 模式（自定义指令分析）

传入一段视频和分析指令，按业务需求对视频内容进行理解。

请求

POST /?ci-process=AIMediaAnalysis HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=AKID****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff905****
Host: examplebucket-1250000000.ci.ap-nanjing.myqcloud.com
Content-Length: 560
Content-Type: application/xml

<Request>
    <Input>
        <Message>
            <Content>
                <Part>
                    <Type>Video</Type>
                    <Url>https://example.com/warehouse_monitor.mp4</Url>
                    <Fps>0.5</Fps>
                </Part>
                <Part>
                    <Type>Text</Type>
                    <Text>请统计视频中出现的人物数量，描述他们的着装与主要活动，并指出是否存在异常行为。</Text>
                </Part>
            </Content>
        </Message>
    </Input>
    <Conf>
        <Type>Custom</Type>
    </Conf>
</Request>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 960
Connection: keep-alive
Date: Mon, 28 May 2026 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<Response>
    <Code>0</Code>
    <Message>OK</Message>
    <State>Success</State>
    <AnalysisResult>
        <Type>Custom</Type>
        <CustomResult>
            <CustomOutput>视频中共出现 2 个主要人物：一名穿蓝色工服的男性（全程出现）和一名穿红色外套的女性（在第 30 秒左右进入画面）。主要活动为货物搬运，未发现异常行为。</CustomOutput>
        </CustomResult>
        <MediaInfo>
            <Duration>62.0</Duration>
            <Fps>0.5</Fps>
            <BilledFrameCount>31</BilledFrameCount>
        </MediaInfo>
    </AnalysisResult>
</Response>

错误码

除 公共错误码 外，本接口可能返回如下错误码：
错误码
HTTP 状态码
描述
NoMediaProvided
400
请求中未包含视频类型的 Part
TooManyVideoParts
400
请求中包含多个视频类型的 Part，本期仅支持1个
UnsupportedPartType
400
传入了本期不支持的 Part 类型，如 Audio
InvalidArgument
400
参数取值非法
MediaTooLarge
400
视频大小超过100MB
MediaDurationExceeded
400
视频时长超过20分钟
MediaDecodeFailed
400
视频解码失败，文件损坏或格式不支持，包含无法读取视频时长的场景
TextTooLong
400
单个 Text 内容超过2048字符
SnapshotFailed
500
后端抽帧异常
ModelCallFailed
500
底层大模型调用失败
ModelTimeout
500
底层大模型调用超时
ProcessTimeout
504
同步处理超时（超过300秒），建议调小 Fps 取值
中国站