Capture Screenshot at Specified Video Timestamps

API Description

1、通过视频id添加单个视频指定时间点截图任务
2、接口URL中的{userid}为点播账号userid，具体参考菜单【使用须知】->【获取密钥】
3、接口支持https协议

API URL

http://api.polyv.net/v2/video/snapshot/{userid}/addTask

Online API Call

Request Method

POST

API Constraints

1. The interface supports both HTTP and HTTPS. HTTPS is recommended to ensure interface security. API calls have frequency limits. See details

Request Parameters

Example

http://api.polyv.net/v2/video/snapshot/1b448be323/addTask

Form Parameters:

vid=1b448be32303e4922a8f70d6b48220ae_1&offsetTimes=5,10,15,20&width=300&sign=4FEC87EC6841211C36EC51A072A6D64DF72E1AF4&ptime=1617700224540&height=300

Response Parameters

Callback Description

The screenshot task result callback notifies users of the task outcome in a timely manner.

Principle

Sends a POST request to the callbackUrl (callback address) via HTTP protocol to notify users of the task result.

Example

After the screenshot task is completed, polyv will call back this interface with signature information. Developers can verify whether the call is a legitimate polyv call using the signature. The specific signature rule: md5("snapshot" + vid + secretKey). For example, if vid="e6b23c6f51350f106556806a576b1942_e" and secretKey="testKey", then sign="3adb60893894d422d00ed2efae8c41f3" (lowercase md5). The final callback URL is http://example.polyv.net/snapshot-callback.do?sign=3adb60893894d422d00ed2efae8c41f3

Successful task callback information:

{
    "taskId": 123,
    "vid": "e6b23c6f51350f106556806a576b1942_e",
    "status": "success",
    "snapshots": [
        {
            "offsetTime": 12,
            "imageUrl": "http://vod-assets.videocc.net/snapshot/e6b23c6f51/e6b23c6f519df1d317cca208edd448cb/12.jpg"
        },
        {
            "offsetTime": 78,
            "imageUrl": "http://vod-assets.videocc.net/snapshot/e6b23c6f51/e6b23c6f519df1d317cca208edd448cb/78.jpg"
        }
    ]
}

Failed task callback information:

{
    "taskId": 123,
    "vid": "e6b23c6f51350f106556806a576b1942_e",
    "status": "fail",
    "snapshots": []
}

Callback Field Description

Snapshots Parameter Description

Java Request Example

For quick integration, please download the relevant dependency source code. Click here to download source code. After downloading, add it to your own source project. The test cases include HttpUtil.java and VodSignUtil.java in the downloaded file.

It is strongly recommended to use the VOD Java SDK for API integration. The VOD Java SDK provides unified encapsulation and optimization for API call logic, exception handling, data signing, and HTTP request thread pools.

private static final Logger log = LoggerFactory.getLogger(VodSnapshotTest.class);
/**
 * 指定视频时间点截图
 * @throws Exception
 * @throws NoSuchAlgorithmException
 */
@Test
public void testAddSnapshotTask() throws Exception, NoSuchAlgorithmException {
    //公共参数,填写自己的实际参数
    String secretKey = super.secretKey;
    String userId = super.userId;
    String ptime = String.valueOf(System.currentTimeMillis());
    //业务参数
    String url = String.format("http://api.polyv.net/v2/video/snapshot/%s/addTask", userId);
    String vid = "1b448be32303e4922a8f70d6b48220ae_1";
    String offsetTimes = "5,10,15,20";
    String width = "300";
    String height = "300";
    String callbackUrl = "http://example.polyv.net/snapshot-callback.do";
    
    Map<String, String> requestMap = new HashMap<>();
    requestMap.put("ptime", ptime);
    requestMap.put("vid", vid);
    requestMap.put("offsetTimes", offsetTimes);
    requestMap.put("width", width);
    requestMap.put("height", height);
    requestMap.put("callbackUrl", callbackUrl);
    requestMap.put("sign", VodSignUtil.getSign(requestMap, secretKey));
    String response = HttpUtil.postFormBody(url, requestMap);
    log.debug("测试指定视频时间点截图,{}", response);
    //do somethings
    
}

Response Example

For global system error descriptions, see Global Error Description

Success Example

{
    "code": 200,
    "status": "success",
    "message": "success",
    "data": 2036
}

Error Example

Incorrect Signature

{
    "code": 400,
    "status": "error",
    "message": "the sign is not right",
    "data": ""
}