Information Submission Interface
Request specification
- Request URL:
Get it from the Console - Service Configuration
- Interface description:
Submit the video information to the interface. After the information is submitted, screenshots of the video will be detected, and the results need to be obtained by calling the Result Obtaining Interface.
- Supported Formats:
Audio package formats supported by the detection interface:wav、mp3、aac、amr、3gp、m4a、wma、ogg、ape etc.
- Size limit:
The size of the audio file does not exceed 550M, and the duration is less than 5 hours
- 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 | Required | Type | Description| |
---|---|---|---|
type | Required | Number | 1:Audio URL 2: Audio BASE64 value |
lang | Required | String | language:Simplified Chinese(zh-CN);Support more languages in the future |
audio | Required | Srting | Audio content, if type=1, then the value is the Audio URL, if type=2, then the value is Audio BASE64 value. When type is 2, then the Audio must be less than 10m. |
audioName | Optional | String | Audio file name,When type=2 and audio is BASE64 value, this parameter is essential and can indicate audio format |
strategyId | Optional | String | Strategy number, use DEFAULT if no this param in request |
userId | Optional | Srting | Unique end user ID. The user ID should be no more than 32 characters. |
userIP | Optional | Srting | User IP address |
did | Optional | Srting | User device ID |
dtype | Optional | Srting | 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,ap |
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 { "type":1, "lang":"zh-CN", "audio":"http://xxx.xxx.com/xxxx", "userId": "testUser" }
-
Request signature:
When the user requests the 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 validates the signature to be consistent and the user corresponding to the appId has permission to operate the requested resource, then 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: *****
- Signature calculation method
- 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))
-
Constructs the signed string StringToSign ("\n" stands for ASCII newline character):
StringToSign = HTTPMethod + “\n” + HostHeaderInLowercase + “\n” + HTTPRequestURI + “\n” + CanonicalizedQueryString
+ “\n” + “X-AppId:” + SAME_APPID_IN_HEADER + “\n” + “X-TimeStamp:” + SAME_TIMESTAMP_IN_HEADER
HTTPRequestURI is the absolute path to the request URI, not containing the CanonicalizedQueryString. If the HTTPRequestURI is empty, a forward slash (/) will be retained.
The hash-based message authentication code (HMAC) is created using the HMAC-SHA256 protocol and then the signature is calculated.
-
StringToSign serves as the signature string, secretKey serves as the secret key and SHA256 serves as the hash algorithm.
For more information about HMAC, see: https://tools.ietf.org/html/rfc2104。
-
Converting the results of the previous step to a BASE64 string
-
Put the BASE64 string into the Authorization of HTTP request Header
- Example of signature
Below is an example of appId & secretKey & video
appId=***
secrectKey=****
audio_url="http://xxx.xxx.com/xxxx"
Below is an example of request body.
{
"type": 1,
"audio":"http://xxx.xxx.com/xxxx",
"userId": "12345678"
}
Generate CanonicalizedQueryString
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
Generate StringToSign
POST
asafe.ilivedata.com
/api/v1/audio/check/submit
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:****
X-TimeStamp:2020-07-31T07:59:03Z
Signatures from HMAC calculations
****
HTTP Response
Content-Type: application/json;charset=UTF-8
The result is in the JSON format, please refer to the following example.
- HTTP response
Description of returning json fields
Field Name | Type | Descriptioin |
---|---|---|
errorCode | Number | Error code:0 means success |
errorMessage | String | Error message |
result | JSON object | Result message |
result:
Field Name | Type | Description |
---|---|---|
taskId | String | Task id, used to call the Video Result Obtaining Interface |
-
Response example 1:
JSON response
{ "errorCode": 0, "result": { "taskId":"f67fee0890de4c118d4f672b7c8ee304" } }
Error code
Http Status code | Error code | Error message |
---|---|---|
200 | 0 | This field is omitted |
405 | 1004 | Method Not Allowed |
411 | 1007 | Not Content Length |
400 | 1002 | API Not Found |
400 | 1003 | Bad Request |
401 | 1102 | Unauthorized Client |
401 | 1106 | Missing Access Token |
401 | 1107 | Invalid Token |
401 | 1108 | Expired Token |
401 | 1110 | Invalid Client |
400 | 2000 | Missing Parameter |
400 | 2001 | Invalid Parameter |