媒体处理智能横转竖能力接入-实践教程-文档中心-腾讯云

介绍
什么是横转竖
横转竖不是单纯的旋转，而是通过识别感兴趣区域 （ROI，Region of Interest），将视频裁剪成一定比例的适合移动设备播放的视频。横转竖提供批量生成短视频的能力，能够将现有的横屏视频资源转换成竖屏视频资源。
输入及输出格式
输入视频文件支持以下格式：
编码标准：MPEG 、H.264、H.265。
封装格式：.mp4、.avi、.mkv、.mov、.mpg。
输出视频文件统一使用 H.264 编码、.mp4 格式。可以使用 Chrome 浏览器预览视频。如果需要转码和转封装格式，可以在本地处理或使用 MPS 提供的音视频转码功能。
接入方式一：API 发起任务
1. 调用 API
您可以直接向腾讯云发起 POST 请求，接口请求域名：mps.tencentcloudapi.com。调用 媒体处理接口 ，选择 AiAnalysisTask 任务，将 Definition 设置为 28（预设智能横转竖模板）。ExtendedParameter 为扩展参数，其值为转义后的 json 字符串，具体参数含义见下文 扩展参数说明 部分。
﻿
﻿
﻿
﻿请求示例
说明：
目前智能横转竖功能支持两种输入来源：腾讯云对象存储（COS）、URL 下载地址。暂不支持 AWS S3。
{
    "Action": "ProcessMedia",
    "Version": "2019-06-12",
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {
            "Url": "https://..." // 替换成需要横转竖的 URL，或者参考“发起媒体处理”接口文档
        }
    },
    "OutputStorage": {
        "CosOutputStorage": {
            "Bucket": "BucketName",
            "Region": "BucketRegion"
        },
        "Type": "COS"
    },
    "OutputDir": "/mycos/htv_test/result/",
    "AiAnalysisTask": {
        "Definition": 28, // 预设横转竖模版 ID
        "ExtendedParameter": "{\\"htv\\": {\\"AlgorithmType\\": 2,\\"FaceDetect\\": 1,\\"FaceDetectConfig\\": {\\"FaceScoreThd\\": 80}}}"
    }
     "TaskNotifyConfig": {
        "NotifyType": "URL",
        "NotifyUrl": "http://callback_url"
    }
}
2. API Explorer 快速验证
您也可以通过 API Explorer 实现快速验证，进入页面填写相关参数信息后即可发起 API 在线调用。
﻿
﻿
﻿
注意：
API explorer 会自动转换，ExtendedParameter 填写对应 json 即可，不用转换成字符串。如果是直接调用 API，那么需要对 json 字符串转义。
转义前后字符串如下：
// 转义前 Unformated
{
    "htv": {
        "AlgorithmType": 2,
        "FaceDetect": 1,
        "FaceDetectConfig": {
            "FaceScoreThd": 80
        }
    }
}
// 转义后
// {\\"htv\\": {\\"AlgorithmType\\": 2,\\"FaceDetect\\": 1,\\"FaceDetectConfig\\": {\\"FaceScoreThd\\": 80}}}
3. 扩展参数说明
扩展参数可以实现特定的能力。由于媒体处理接口无法解析扩展参数，因此 ExtendedParameter 其值为序列化的 json 字符串。传入智能横转竖的 ExtendedParameter 需要放在 htv 下面。以下是一个序列化前的 json 示例，使用 API 时请注意传入转义后的参数：
{
    "htv": {
        "AlgorithmType": 2,
        "FaceDetect": 1,
        "FaceDetectConfig": {
            "FaceScoreThd": 80
        }
    }
}
// 转义前（可在API explorer中使用）： {"htv": {"AlgorithmType": 2,"FaceDetect": 1,"FaceDetectConfig": {"FaceScoreThd": 80}}}
// 转义后（直接调用API时需传入转义后参数）： {\\"htv\\": {\\"AlgorithmType\\": 2,\\"FaceDetect\\": 1,\\"FaceDetectConfig\\": {\\"FaceScoreThd\\": 80}}}
名称
类型
描述
AlgorithmType
Integer
指定算法类别：
1：处理速度较快。
2：支持人脸检测。
Ratio
String
视频横竖比，字符串类型，内部进行解析。如果解析失败会取默认值 9:16 的比例进行裁剪。（例："9:16"，转换成横比竖 9:16 视频，高度取原视频高度）
FaceDetect
Integer
1：开启人脸检测功能（仅支持算法 2，AlgorithmType 2）。
此功能可以在转换视频过程中进行人脸检测。如果一个场景中出现了两个人脸分居两边，会将视频的左右分割后上下拼接。单个人脸或者人脸集中在一个竖屏范围里则使用正常的横转竖识别。
FaceDetectConfig
FaceDetectConfig
人脸检测相关配置。
FaceDetectConfig
名称
类型
描述
FaceScoreThd
Integer
人脸检测算法的识别阈值，仅当人脸识别评分超过该阈值时，才将其视为有效的人脸。
FaceAccuracy
String
可选参数，主要决定人脸检测次数，默认使用 Balance，其他可选项 Efficiency，Precision。
4. 查询任务结果
任务回调：在使用 ProcessMedia 发起媒体处理任务时，可以通过 TaskNotifyConfig 参数设置回调信息。当任务处理完成后，会通过配置的回调信息回调任务结果，您可以通过 ParseNotification 解析事件通知结果。下方列出了相关数据结构以供参考。
接口查询任务：使用 ProcessMedia 返回的 TaskId 调用 查询任务详情 接口查询任务处理结果。解析 WorkflowTask 下的 AiAnalysisResultSet 字段即可。下方列出了相关数据结构以供参考。
控制台查询任务：进入控制台 点播任务管理，任务列表中会展示刚发起的任务。
﻿
﻿
﻿
﻿当子任务状态为“成功”时，您可以进入 COS Bucket > 输出 Bucket 中，找到您的输出目录，目录下htv-开头的文件即为智能横转竖处理后的输出视频。
﻿
﻿
﻿
相关数据结构
AiAnalysisTaskHorizontalToVerticalResult
智能横转竖结果类型。
被如下接口引用：DescribeTaskDetail, ParseNotification。
名称
类型
描述
Status
String
任务状态，有 PROCESSING，SUCCESS 和 FAIL 三种。
ErrCode
Integer
错误码，0：成功，其他值：失败。
Message
String
错误信息。
Input
AiAnalysisTaskHorizontalToVerticalInput
智能横转竖任务输入。
Output
AiAnalysisTaskHorizontalToVerticalOutput
智能横转竖任务输出。
注意：此字段可能返回 null，表示取不到有效值。
AiAnalysisTaskHorizontalToVerticalInput
智能横转竖任务输入类型。
被如下接口引用：DescribeTaskDetail, ParseNotification。
名称
类型
描述
Definition
Integer
视频智能横转竖模板 ID。
AiAnalysisTaskHorizontalToVerticalOutput
智能横转竖结果信息。
被如下接口引用：DescribeTaskDetail, ParseNotification。
名称
类型
描述
Path
String
视频智能横转竖列表。
OutputStorage
TaskOutputStorage
智能横转竖视频的存储位置。
注意：此字段可能返回 null，表示取不到有效值。
接入方式二：控制台发起任务（零代码）
1. 创建任务
1.1 进入 媒体处理控制台，依次点击创建任务 > 快速创建点播处理任务。
﻿
﻿
﻿
1.2 首先指定输入视频文件，目前智能横转竖功能支持两种输入来源：腾讯云对象存储（COS）、URL下载地址。暂不支持 AWS S3。
1.3 然后，在步骤“处理输入文件”处，加入智能分析节点。
﻿
﻿
﻿
在弹出的智能分析设置抽屉中，选择预设智能横转竖模板（模板ID：28）。
说明：
若您期望给自定义智能分析模板开启智能横转竖功能，可以联系我们并同步模板 ID，腾讯云媒体处理开发人员将为您配置并启动智能横转竖功能。
﻿
﻿
﻿
1.4 最后，指定输出视频保存路径后，即可单击创建发起任务。
﻿
﻿
﻿
2. 查询任务结果
参考上文 查询任务结果。
3. 自动触发任务（可选能力）
若您希望实现：在 COS 桶中上传了视频文件，自动按照预设参数进行智能横转竖处理。您可以：
3.1 在创建任务时单击保存此编排，在弹出的窗口中配置触发 Bucket、触发目录等参数。
﻿
﻿
﻿
3.2 然后进入点播编排列表，找到刚创建好的编排，在启动处开启按钮即可。后续在触发目录下新增的视频文件，将自动按照该编排预设的流程和参数发起任务，并将处理后的视频文件保存到编排配置的输出路径中。
注意：
启用编排成功后，需要3~5分钟才会生效。
﻿
﻿
﻿
﻿

名称	类型	描述
AlgorithmType	Integer	指定算法类别： 1：处理速度较快。 2：支持人脸检测。
Ratio	String	视频横竖比，字符串类型，内部进行解析。如果解析失败会取默认值 9:16 的比例进行裁剪。（例："9:16"，转换成横比竖 9:16 视频，高度取原视频高度）
FaceDetect	Integer	1：开启人脸检测功能（仅支持算法 2，AlgorithmType 2）。此功能可以在转换视频过程中进行人脸检测。如果一个场景中出现了两个人脸分居两边，会将视频的左右分割后上下拼接。单个人脸或者人脸集中在一个竖屏范围里则使用正常的横转竖识别。
FaceDetectConfig	FaceDetectConfig	人脸检测相关配置。

智能横转竖能力接入

本页目录：

介绍

什么是横转竖

输入及输出格式

接入方式一：API 发起任务

1. 调用 API

﻿请求示例

2. API Explorer 快速验证

3. 扩展参数说明

FaceDetectConfig

4. 查询任务结果

相关数据结构

AiAnalysisTaskHorizontalToVerticalResult

AiAnalysisTaskHorizontalToVerticalInput

AiAnalysisTaskHorizontalToVerticalOutput

接入方式二：控制台发起任务（零代码）

1. 创建任务

2. 查询任务结果

3. 自动触发任务（可选能力）

请求示例