视频编辑 - 点播

开发者中心

点播

服务端 API

视频编辑

更新时间： 2025/01/17 16:34:52

视频裁剪

接口描述

域名：vcloud.163.com

接口名：/app/vod/video/clip

对视频进行裁剪，针对每个采样区间生成独立的视频。

输入参数

参数	类型	必须	说明
vid	Long	是	视频的标识
format	Int	是	生成的视频预览格式，1表示mp4格式，2表示flv格式
samplings	List	是	采样的视频时间区间列表，包含一组sampling，区间个数最多10个，单位为秒，可以有重合，区间顺序有意义
callbackUrl	String	否	处理完成后回调的URL地址（需标准http格式），如不设置，使用默认的回调地址
userDefInfo	String	否	用户自定义信息，回调会返回此信息

sampling参数详细说明

参数	类型	必须	说明
start	Int	是	采样的视频时间区间开始时间(单位秒)
end	Int	是	采样的视频时间区间结束时间(单位秒)
cropArea	object	否	采样区间内对画面进行扣取

cropArea参数说明

参数	类型	必须	说明
width	Int	是	扣取画面的宽，例如640，50，此值可表示绝对值也可表示相对值，取决于whType，当whType取值为2时，不允许大于100
height	Int	是	扣取画面的高，例如360,50，此值可表示绝对值也可表示相对值，取决于whType，当whType取值为2时，不允许大于100
whType	Int	是	取值1或者2。1-表示上面的宽高为绝对值，传入为640360，那么扣取画面的宽高就是640360；2-表示相对值，表示传入的宽高为相对原视频宽高的百分比。例如传入5050，那么扣取的视频画面宽为src_width50%，同理高为src_height*50%
x	Int	是	采样画面左上角相对于原视频的左上角的横坐标(单位像素)
y	Int	是	采样画面左上角相对于原视频的左上角的纵坐标(单位像素)
xyType	Int	是	用于表示x,y是绝对值还是百分比，1-绝对值，例如120,120。2-百分比，表示才用原视频宽高的百分比

callbackUrl如果不设置，会采用默认的视频裁剪地址回调。默认视频裁剪地址回调设置接口参见设置回调地址。

输出参数

参数	类型	说明
requestId	String	请求标识
code	Int	状态码
taskId	Long	任务标识
msg	String	错误信息

taskId是媒体处理任务的唯一标识，用户可以通过taskId主动查询任务的执行状态。详情请参见任务查询。

响应状态码

状态码	含义
200	操作成功
400	请求报文格式错误，报文构造不正确或者没有完整发送
700	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
710	权限认证失败，请参考文档中的接口鉴权部分
720	访问失败，余额不足。
721	服务未开通，请前往开通页面申请服务开通
722	服务开通审核中，请联系客服人员开通服务
723	请求的次数超过了配额限制

示例代码

输入1

curl -X POST \
https://vcloud.163.com/app/vod/video/clip \
-H "Content-Type: application/json;charset=utf-8" \ 
-H "AppKey: 027338bf05cc4***9d6af80b3" \ 
-H "Nonce: 1" \
-H "CurTime: 1465723418" \
-H "CheckSum: 61bbfd88c51028a2***4e65a2abe7ae13" \
-d '{
    "vid":32,
    "format":1,
    "samplings":[
        {
            "start":1,
            "end":3
            "cropArea":{
                "width":120,
                "height":120,
                "whType":1,
                "x":0,
                "y":0,
                "xyType":1
            }
        },
        {
            "start":4,
            "end":6,
            "cropArea":{
                "width":20,
                "height":20,
                "whType":2,
                "x":0,
                "y":0,
                "xyType":1
            }
        },
        {
            "start":8,
            "end":9
        },
        {
            "start":12,
            "end":13
        },
        {
            "start":21,
            "end":23
        }
    ],
    "userDefInfo":"userId=123456"
}'

输出1

{
    "requestId" : "vode49fdc9a-d59d-480d-b3ef-c9***664",
    "code" : 200,
    "ret": {
    "taskId": 5
    }
}

结果回调

视频裁剪的生成为异步处理，处理完成会回调给请求参数设置的callbackUrl，如果未设置，回调给默认的裁剪地址。

视频裁剪回调内容示例

{
    "videoClipJobResult":[
        {
            "sampling":{
                "start":1,
                "end":3,
                "cropArea":{
                    "width":120,
                    "height":120,
                    "whType":1,
                    "x":0,
                    "y":0,
                    "xyType":1
                }
            },
            "status":"SUCCESS",
            "vid":111
        },
        {
            "sampling":{
                "start":4,
                "end":6,
                "cropArea":{
                    "width":20,
                    "height":20,
                    "whType":2,
                    "x":0,
                    "y":0,
                    "xyType":1
                }
            },
            "status":"SUCCESS",
            "vid":112
        },
        {
            "sampling":{
                "start":8,
                "end":9
            },
            "status":"FAILED",
            "msg":"Fail"
        }
    ],
    "type":"VIDEO_CLIP",
    "originVid":1021,
    "user_defined":"userId=123456",
    "requestId":"vode49fdc9a-d59d-480d-b3ef-c91b***f664"
}

请以实际收到的body字段为准，以下仅为body字段示例。

参数	类型	说明
type	String	回调类型，视频裁剪生成回调固定为“VIDEO_CLIP”
originVid	Long	原始视频文件视频标识
user_defined	String	用户自定义字段值
requestId	String	用户调用视频裁剪接口时返回的请求标识
videoClipJobResult	Json对象	视频裁剪任务结果

videoClipJobResult参数详细说明

参数	类型	说明
sampling	String	采样的视频时间区间
status	String	状态，FAILED 处理失败 SUCCESS 处理成功
vid	Long	采样区间生成的对应视频ID

sampling为实际生成视频的区间，例如设置区间[1, 11] 但是视频实际时长只有10,则返回的区间是[1,10]。

视频合并

视频合并会将多个视频合成一个视频，点播服务会对各单一视频进行转码处理，调用该功能会产生对应的转码费用，具体价格请参见点播价格详情页。

接口描述

域名：vcloud.163.com

接口名：/app/vod/nts/merge

1.视频合并，来源视频必须是点播库中的视频，参数为vid视频id；

2.仅支持一次性合并20个视频；

3.来源视频的总时长不得超过8小时；

4.因为来源视频的分辨率、bit等都不尽相同，现在默认使用时长最长的视频的分辨率等参数；

5.分辨率等比例缩放时，如果高度为最大时，宽度使用填充黑边，反之高度使用填充黑边（具体可以使用widthCutStyle、heightCutStyle指定）；

例如：最大时长的分辨率是1000(宽)*800（高）,比例是1000/800。 其中一个视频的分辨率是500*300，则等比例缩放到1000*800后，高度不够的使用填充黑边；

6.提交后的任务，可以通过回调接口接收回调信息，也可以通过taskId主动查询任务的执行状态。详情请参见任务查询。

输入参数

参数	类型	必须	说明
videos	Array	是	待合并的视频列表（长度不超过20），参见 MergeVideo 参数说明
widthCutStyle	Int	否	参见 KeepAspectRatioStyle 参数说明, 默认填充黑边
heightCutStyle	Int	否	参见 KeepAspectRatioStyle 参数说明, 默认填充黑边
callbackUrl	String	否	处理完成后回调的URL地址（需标准http格式）
userDefInfo	String	否	用户自定义信息，回调会返回此信息
audioParam	Object	否	背景音乐文件信息(如果为视频，则取其音轨)，参见 AudioParam 参数说明
imageId	Int	否	视频封面图片ID

MergeVideo 参数详细说明

参数	类型	必须	说明
vid	Long	是	视频id
start	Long	否	视频截取开始时间，默认0(单位秒)
end	Long	否	视频截取结束时间秒，默认视频时长(单位秒)

KeepAspectRatioStyle 参数详细说明

参数值	类型	说明
0	Int	填充黑边
1	Int	平均切割
2	Int	如果要切宽的时候只切左边保留右边
3	Int	如果要切宽的时候只切右边保留左边
4	Int	如果要切高的时候只切上边保留下边
5	Int	如果要切高的时候只切下边保留上边

AudioParam 参数详细说明

参数	类型	必须	说明
vid	Long	是	音视频id
bgmLoop	boolean	是	背景音乐是否循环播放
bgmVolume	float	是	背景音乐音量系数必须大于0
bgmFadeInTime	Int	否	背景音乐渐入持续时间，大于等于0(默认0)
bgmFadeOutTime	Int	否	背景音乐渐出持续时间，大于等于0(默认0)

callbackUrl如果不设置，会采用默认的视频合并地址回调。默认设置视频合并地址回调请参见设置回调地址。

输出参数

参数	类型	说明
requestId	String	请求标识
code	Int	状态码
taskId	Long	任务标识
msg	String	错误信息

响应状态码

状态码	含义
200	操作成功
400	请求报文格式错误，报文构造不正确或者没有完整发送
700	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
710	权限认证失败，请参考文档中的接口鉴权部分
720	访问失败，余额不足
721	服务未开通，请前往开通页面申请服务开通
722	服务开通审核中，请联系客服人员开通服务
723	请求的次数超过了配额限制

示例代码

输入1

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf0***b5d98bc9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c51028a2***28584e65a2abe7ae13" -d '{"videos":[{"vid":123}],"widthCutStyle":1,"heightCutStyle":3,"userDefInfo":"job_id:123132"}' https://vcloud.163.com/app/vod/nts/merge

输出1

{
    "requestId" : "vode49fdc9a-d59d-480d-b3ef-c91***8f664",
    "code" : 200,
    "ret": {
    "taskId": 5
    }
}

结果回调

视频合并的生成为异步处理，处理完成会回调给请求参数设置的callbackUrl，如果未设置，回调给默认的视频合并地址。

视频裁剪回调内容示例

{
    "taskId" : 214123123,
    "status": "SUCCESS",
    "failMsg": "asdasdasd",
    "vid": 1010,
    "jobRequestId": "vod213asdd12313asd123123"  //任务追踪用
}

请以实际收到的body字段为准，以下仅为body字段示例。

参数	类型	说明
taskId	Long	媒体处理任务标识
status	String	任务状态，SUCCESS表示成功
vid	Long	合并后的视频文件标识
failMsg	String	失败原因
jobRequestId	String	用户调用视频合并接口时返回的请求标识

任务查询

用于查询异步处理的任务。

接口描述

域名：vcloud.163.com

接口名：/app/vod/task/get

通过任务ID查询任务执行状况。仅支持查询最近7天的任务信息。

输入参数

参数	类型	必须	说明
taskId	Long	是	任务标识

输出参数

参数	类型	说明
requestId	String	请求标识
code	Int	状态码
msg	String	错误信息
ret	JSON对象	结果集，JSON对象
ret.task	JSON对象	任务执行状况
input	JSON对象	任务输入
input.vid	Long	任务输入视频标识
result	JSON对象	任务输出结果
result.videoClipJobResult	JSON对象	视频裁剪任务结果，参见videoClipJobResult参数详细说明
status	String	任务状态： INIT表示提交中，FAILED表示处理失败， PROCESSING表示处理中， SUCCESS表示处理成功
taskId	Long	任务标识
type	String	任务类型： VIDEO_CLIP表示视频裁剪任务， MERGE_VIDEO表示视频合并任务
userDefinedInfo	String	用户自定义信息
failMsg	String	失败原因
createTime	String	任务创建时间 yyyy-MM-dd HH:mm:ss
endTime	String	任务结束时间 yyyy-MM-dd HH:mm:ss

videoClipJobResult参数详细说明

参数	类型	说明
sampling	String	采样的视频时间区间
status	String	状态，FAILED表示处理失败， SUCCESS表示处理成功
vid	Long	采样区间生成的对应视频ID

sampling为实际生成视频的区间，例如设置区间[1, 11] 但是视频实际时长只有10,则返回的区间是[1,10]

响应状态码

状态码	含义
200	操作成功
400	请求报文格式错误，报文构造不正确或者没有完整发送
700	服务器内部出现错误，请稍后重试或者将完整错误信息发送给客服人员帮忙解决
710	权限认证失败，请参考文档中的接口鉴权部分
720	访问失败，余额不足。
721	服务未开通，请前往开通页面申请服务开通
722	服务开通审核中，请联系客服人员开通服务
723	请求的次数超过了配额限制

示例代码

输入1

    curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "AppKey: 027338bf05cc4a6***c9d6af80b3" -H "Nonce: 1" -H "CurTime: 1465723418" -H "CheckSum: 61bbfd88c5102***e65a2abe7ae13" -d '{"taskId":1}' https://vcloud.163.com/app/vod/task/get

视频裁剪任务查询输出

{
    "ret": {
        "task": {
            "createTime": "2018-11-22 15:32:55", 
            "endTime": "2018-11-22 15:33:02", 
            "failMsg": "", 
            "input": {
                "vid": 24
            }, 
            "result": {
                "videoClipJobResult": [
                    {
                        "sampling": {
                            "start": 1, 
                            "end": 3
                        }, 
                        "status": "SUCCESS", 
                        "vid": 111
                    }, 
                    {
                        "sampling": {
                            "start": 4, 
                            "end": 6
                        }, 
                        "status": "SUCCESS", 
                        "vid": 112
                    }, 
                    {
                        "sampling": {
                            "start": 8, 
                            "end": 9
                        }, 
                        "status": "FAILED", 
                        "msg": "Fail"
                    }
                ]
            }, 
            "status": "SUCCESS", 
            "taskId": 1, 
            "type": "VIDEO_CLIP", 
            "userDefinedInfo": ""
        }
    }, 
    "requestId": "vodc90605aa****0a041a0506d9", 
    "code": 200
}

视频合并任务查询输出

{
    "ret": {
        "task": {
            "createTime": "2018-12-06 17:51:34",
            "endTime": "2018-12-06 17:52:22",
            "failMsg": "",           
            "result": {
                "vid": 1
            },
            "status": "SUCCESS",
            "taskId": 1,
            "type": "MERGE_VIDEO",
            "userDefinedInfo": "auto视频合并"
        }
    },
    "requestId": "vod8867f143****1e2025af61e3",
    "code": 200
}

此文档是否对你有帮助？

有帮助

去反馈

视频裁剪
接口描述
输入参数
sampling参数详细说明
cropArea参数说明
输出参数
响应状态码
示例代码
结果回调
视频裁剪回调内容示例
videoClipJobResult参数详细说明
视频合并
接口描述
输入参数
MergeVideo 参数详细说明
KeepAspectRatioStyle 参数详细说明
AudioParam 参数详细说明
输出参数
响应状态码
示例代码
结果回调
视频裁剪回调内容示例
任务查询
接口描述
输入参数
输出参数
videoClipJobResult参数详细说明
响应状态码
示例代码