Crop a video file

The API is used to crop a video file. Independent videos are created for each sampling interval.

URL

POST https://vcloud.163.com/app/vod/video/clip

Request parameters

Parameter	Type	Required	Description
vid	Long	Yes	The identifier of a video file.
format	Int	Yes	The video preview format. 1: MP4. 2: FLV.
samplings	List	Yes	The list of video intervals for sampling, including a set of sampling. Up to 10 intervals can be listed. Unit: seconds. Intervals can overlap and the interval sequence is sensitive.
callbackUrl	String	Optional	The URL of the callback after the processing is complete. The URL must use the standard HTTP. If the parameter is not specified, the default URL is used.
userDefInfo	String	Optional	User-defined information, which is returned in the notification sent by the callback.

sampling schema

Parameter	Type	Required	Description
start	Int	Yes	The start time of a sample video interval.
end	Int	Yes	The end time of a sample video interval.
cropArea	object	Optional	The image is cropped in the sampling interval.

cropArea schema

Parameter	Type	Required	Description
width	Int	Yes	The cropped screen width, such as 640 and 50. This value can represent an absolute value or a relative value, depending on whType. If the value of whType is set to 2, the value is not allowed to be greater than 100.
height	Int	Yes	The cropped screen height, such as 360 and 50. This value can represent an absolute value or a relative value, depending on whType. If the value of whType is set to 2, the value is not allowed to be greater than 100.
whType	Int	Yes	Valid values: 1 and 2. A value of 1 indicates that the previous width and height are absolute values. If the specified value is 640*360, then the width and height of the cropped image is 640*360. A value of 2 indicates a relative value, which indicates that the width and height are percentage with respect to the original video width and height. For example, if 50*50 is specified, the width of the cropped video screen is src_width*50%, and the height is src_height*50%.
x	Int	Yes	The x coordinate of the upper left corner of the sampling screen with respect to the original video.
y	Int	Yes	The y coordinate of the upper left corner of the sampling screen with respect to the original video.
xyType	Int	Yes	Determines whether to use an absolute value or a percentage for x and y values. 1: absolute value, For example, 120,120. 2: percentage, the percentage of the original video width and height is used.

If callbackUrl is not specified, the default callback address will be used for video cropping. For more information about how to specify the default callback URL for video cropping, see Set a callback URL.

Response parameters

Parameter	Type	Description
requestId	String	The request identifier.
code	Int	The status code.
taskId	Long	The task ID.
msg	String	The error message.

The task ID is the unique identifier of the media processing task. You can query the status of the task using taskId. For more information, see Query a task.

Response status codes

Status code	Description
200	The operation was successful.
400	The request message format is invalid. The message structure is invalid, or the message is incomplete.
700	An internal server error occurred. Try again later or send the complete error message to customer service for help.
710	Authorization failed. See the authentication section in the specified API reference.
720	Access failed. The account has an insufficient balance.
721	The service has not been activated. You can activate the service on the product page.
722	The application to activate the service is under review. You can contact customer service for help.
723	The number of requests exceeds the upper limit.

Example

curl request example

curl -X POST \
https://vcloud.163.com/app/vod/video/clip \
-H "Content-Type: application/json;charset=utf-8" \ 
-H "AppKey: 027338bf05cc4a65b5d98bc9d6af80b3" \ 
-H "Nonce: 1" \
-H "CurTime: 1465723418" \
-H "CheckSum: 61bbfd88c51028a2a28b3628584e65a2abe7ae13" \
-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"
}' 

Sample response

"Content-Type": "application/json; charset=utf-8"
{
	"requestId" : "vode49fdc9a-d59d-480d-b3ef-c91b37f8f664",
	"code" : 200,
	"ret": {
	"taskId": 5
    }
}

The callbacks to return the results.

The video cropping task is asynchronously performed. After the processing is complete, the callback sends notifications using the URL specified in callbackUrl. If unspecified, the callback will send notifications using the default crop URL.

Sample return of a video cropping task

{
    "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-c91b37f8f664"
}

The parameters are contained in the body of the example response. You must use actual parameters for your purpose.

Parameter	Type	Description
type	String	The callback type. Set the value to VIDEO_CLIP.
originVid	Long	The video identifier of a source video file.
user_defined	String	The user-defined field value.
requestId	String	The request ID returned when the user calls the video cropping API.
videoClipJobResult	JSON	The result of a video cropping task.

videoClipJobResult schema

Parameter	Type	Description
sampling	String	The video interval for sampling.
status	String	The task status. Valid values: FAILED and SUCCESS.
vid	Long	The ID of a video file generated in the sampling interval.

Sampling is the interval in which the video is generated. For example, if the interval is set to [1, 11], but the actual duration of the video is only 10, the returned interval is [1, 10].

Merge video files

• The source videos must be video files in the VOD library. The videos with IDs specified in the vid parameter are used.

• Up to 20 videos file can be merged at a time.

• The total duration of the source video files cannot exceed 8 hours.

• The resolution and bitrate of the source video files are different. Therefore, the resolution and other parameters of the video file with the longest duration are now used by default;

• If the resolution is scaled proportionally, and the height reaches the maximum value, the width is filled with a black border. Otherwise, the height is filled with a black border. You can use widthCutStyle and heightCutStyle to specify the method.

  For example, the resolution for the maximum duration is 1000 (width) * 800 (height), and the aspect ratio is 1000/800. If the resolution of one of the videos is 500300, and the resolution scales to 1000800, fill the black border for the short section for the height.

• If you submit a task, you can receive the information returned by the callback. You can also query the task using the task ID. For more information, see Query a task.

URL

POST https://vcloud.163.comPOST /app/vod/nts/merge

Request parameters

Parameter	Type	Required	Description
videos	Array	Yes	The list of videos to be merged. For more information, see MergeVideo schema.
widthCutStyle	Int	Optional	See KeepAspectRatioStyle schema. By default, fill with black border.
heightCutStyle	Int	Optional	See KeepAspectRatioStyle schema, By default, fill with black border.
callbackUrl	String	Optional	The URL of the callback after the processing is complete. The URL must use the standard HTTP.
userDefInfo	String	Optional	User-defined information, which is returned in the notification sent by the callback.
audioParam	Object	Optional	The information about the background music file. if a video is used, take the audio track. For more information, see AudioParam.
imageId	Int	Optional	The ID of a video thumbnail.

MergeVideo schema

Parameter	Type	Required	Description
vid	Long	Yes	The ID of a video file.

KeepAspectRatioStyle schema

Parameter	Type	Description
0	Int	Fill with the black border.
1	Int	Evenly crop
2	Int	Crop the left and keep the right.
3	Int	Crop the right and keep the left.
4	Int	Crop the top and keep the bottom.
5	Int	Crop the bottom and keep the top.

AudioParam schema

Parameter	Type	Required	Description
vid	Long	Yes	The ID of a video file.
bgmLoop	boolean	Yes	Determines whether to play the background music in loop.
bgmVolume	float	Yes	The background music volume. The value must be greater than 0.
bgmFadeInTime	Int	Optional	The time to fade in for the background music. The value must be greater than or equal to 0. The default value is 0.
bgmFadeOutTime	Int	Optional	The time to fade out for the background music. The value must be greater than or equal to 0. The default value is 0.

If callbackUrl is not specified, the default callback URL address will be used for merging videos. For more information about how to specify the default callback URL for merging videos, see Set a callback URL.

Response parameters

Parameter	Type	Description
requestId	String	The request identifier.
code	Int	The status code.
taskId	Long	The task ID.
msg	String	The error message.

Response status codes

Status code	Description
200	The operation was successful.
400	The request message format is invalid. The message structure is invalid, or the message is incomplete.
700	An internal server error occurred. Try again later or send the complete error message to customer service for help.
710	Authorization failed. See the authentication section in the specified API reference.
720	Access failed. The account has an insufficient balance.
721	The service has not been activated. You can activate the service on the product page.
722	The application to activate the service is under review. You can contact customer service for help.
723	The number of requests exceeds the upper limit.

Example

curl request example

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

Sample response

"Content-Type": "application/json; charset=utf-8"
{
	"requestId" : "vode49fdc9a-d59d-480d-b3ef-c91b37f8f664",
	"code" : 200,
	"ret": {
	"taskId": 5
    }
}

The callbacks to return the results.

The video merging task is asynchronously performed. After the processing is complete, the callback sends notifications using the URL specified in callbackUrl. If unspecified, the callback will send notifications using the default video merging URL.

Sample return of a video cropping task

{
    "taskId" : 214123123,
    "status": "SUCCESS",
    "failMsg": "asdasdasd",
    "vid": 1010,
    "jobRequestId": "vod213asdd12313asd123123"  //Track the task.
}

The parameters are contained in the body of the example response. You must use actual parameters for your purpose.

Parameter	Type	Description
taskId	Long	The ID of a media processing task.
status	String	Task status, such as SUCCESS.
vid	Long	The identifier of a merged video file.
failMsg	String	The failure reason.
jobRequestId	String	The request ID returned when the user calls the video merging API.

Query a task

The API is used to query asynchronously processed tasks. You can query task status by using a task ID. Only the information about tasks in the most recent 7 days can be queried.

URL

POST https://vcloud.163.com/app/vod/task/get

Request parameters

Parameter	Type	Required	Description
taskId	Long	Yes	The task ID.

Response parameters

Parameter	Type	Description
requestId	String	The request identifier.
code	Int	The status code.
msg	String	The error message.
ret	JSON object	The result in JSON format.
ret.task	JSON object	The task status.
input	JSON Object	The task Input.
input.vid	Long	The ID of the input video.
result	JSON Object	Task output result.
result.videoClipJobResult	JSON object	The result of a video cropping task. For more information, see videoClipJobResult schema.
status	String	The task status. INIT: submitting. FAILED: processing failed. PROCESSING: processing, SUCCESS: processing succeeded.
taskId	Long	The task ID.
type	String	The task type. VIDEO_CLIP: a video cropping task. MERGE_VIDEO: a video merging task
userDefinedInfo	String	User-defined information.
failMsg	String	The failure reason.
createTime	String	The time when the task is created in yyyy-MM-dd Hh:mm:ss format.
endTime	String	The time when the task is completed in yyyy-MM-dd Hh:mm:ss format.

videoClipJobResult schema

Parameter	Type	Description
sampling	String	The video interval for sampling.
status	String	The task status. Valid values: FAILED and SUCCESS.
vid	Long	The ID of a video file generated in the sampling interval.

Sampling is the interval in which the video is generated. For example, if the interval is set to [1, 11], but the actual duration of the video is only 10, the returned interval is [1, 10].

Response status codes

Status code	Description
200	The operation was successful.
400	The request message format is invalid. The message structure is invalid, or the message is incomplete.
700	An internal server error occurred. Try again later or send the complete error message to customer service for help.
710	Authorization failed. See the authentication section in the specified API reference.
720	Access failed. The account has an insufficient balance.
721	The service has not been activated. You can activate the service on the product page.
722	The application to activate the service is under review. You can contact customer service for help.
723	The number of requests exceeds the upper limit.

sample Example

curl request example

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

Sample return of a video cropping task

"Content-Type": "application/json; charset=utf-8"
{
    "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-24c4-4e17-8b07-0a041a0506d9", 
    "code": 200
}

Sample return of a video merging task

"Content-Type": "application/json; charset=utf-8"
  {
    "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 video merging"
        }
    },
    "requestId": "vod8867f143-a5b3-4e11-a234-1e2025af61e3",
    "code": 200
 }