Information Submission Interface Specification

Update:

1. Parameter specification

  • Request URL:

https://vsafe.ilivedata.com/api/v1/livevideo/check/submit

  • Interface description:

Submit the information related to live video streaming to the interface. After the submission, screenshots of the video will be detected, and the detection results need to be obtained by calling the Result Obtaining Interface.

  • Supported formats:

Streaming protocols supported by the detection interface are as follows: rtp, srtp, rtmp, rtmps, mmsh, mmst, hls, http, tcp, https, etc.

  • HTTP Request Header:
Header Value Description
Content-Type application/json;charset=UTF-8 Request body type
Accept application/json;charset=UTF-8 Accepted return type
X-AppId The only identifier of the project or application
X-TimeStamp The UTC timestamp of the request. Timestamps need to be formatted according to W3C standards, for example: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime)
Authorization Signature value

  • Request method：POST

  • Request body JSON object:

Parameter Essential Type Description
video Essential String URL of live video
frequency Optional Number Default frame extraction setting, there will be one frame captured and detected every 5 seconds, the settable range is 1~60 seconds
lang Optional String Default zh-CN;
userId Optional String Unique end user ID. The user ID should be no more than 32 characters.
userIP Optional String User IP address
did Optional String User device ID
dtype Optional String User device type：1：iPhone 2：android 3: ipad 4：wphone 5: pc 6：web 7：wap
callbackRegion Optional String callback region：default use cn server to do callback，supports : cn,us,eu
callbackUrl Optional String callback url：http
callbackSecretKey Optional String callback secret key, customizable. but is necessary be consistent in your callback signature

  • Example of request body:

    JSON Response
      {
      "video":"http://xxx.xxx.com/xxxx",
      "userId": "testUser"
        }

  • Request signature:

When the user requests Video Submit API, the request can be signed with the appId and secretKey (obtained from the Console - Service Configuration). When the API receives the request with the signature information, it will verify the signature using the same algorithm, and if the signature is found to be inconsistent, the API will return 401 error to the user.

If the API validation signature is consistent and the user corresponding to the appId has permission to operate the requested resource, the request succeeds, otherwise the API returns 401 error.

  • Send signatures by HTTP Request Headers

Method: Add a header named Authorization in the request, whose value is the signature value. For example:

 Authorization: Njl86M/jY6zZaZoGhZdGO+GI/8+yGFECusGH1yQHUFE=
  • Signature calculation method
  1. Canonicalized Query String:

Convert the request body JSON string to a hexadecimal string (not Base64) by doing sha256 encoding with UTF-8 character encoding.

CanonicalizedQueryString = hex(sha256(jsonBody))

  1. Constructs the signed string StringToSign ("\n" stands for ASCII newline character):

    StringToSign = HTTPMethod + “\n” + HostHeaderInLowercase + “\n” + HTTPRequestURI + “\n” + CanonicalizedQueryString < obtain from the previous step > + “\n” + “X-AppId:” + SAME_APPID_IN_HEADER + “\n” + “X-TimeStamp:” + SAME_TIMESTAMP_IN_HEADER

The HTTPRequestURI is the absolute path to the request URI, without the request string. If the HTTPRequestURI is empty, also keep a forward slash (/)

The hash-based message authentication code (HMAC) is created using the HMAC-SHA256 protocol and the signature is calculated.

  1. StringToSign as the signature string, secretKey as the secret key and SHA256 as the hash algorithm.

    For more information about HMAC, see: https://tools.ietf.org/html/rfc2104。

  2. Converting the results of the previous step to a BASE64 string

  3. Put the BASE64 string into the Authorization of HTTP request Header

  • Example of signature

Below is an example of appId & secretKey & video.

appId=1000
secrectKey=d9e23d93053f49ade2f8fce185acedd4
video_url="http://xxx.xxx.com/xxxx"

Below is an example of request type.

{
 "video":"http://xxx.xxx.com/xxxx",
 "userId": "12345678"
}

Generate CanonicalizedQueryString

b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118

Generate StringToSign

POST
vsafe.ilivedata.com
/api/v1/video/check/submit
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:1000
X-TimeStamp:2020-07-31T07:59:03Z

Signatures from HMAC calculations

H0ZXsKUaiRotpxSiXW6+RgKRwnxHXy3qwlVzavs9iHo=