Image/File · Standard API · eKYC Core

Upload video/audio/frames

POST/v1/files

Uploads a video or audio file, or a list of video frames, and returns the file_id for it.

Request

MethodPOST

Path/v1/files

Content-Typemultipart/form-data

Auth requiredYes — HMAC signing

There are two ways to call this, and they take different parameters and different content types.

Name	Type	Required	Description
`file`	file	Optional	the file video/audio to be uploaded
`label`	string	Optional	label of the file
`metadata`	string_json	Optional	key-value, key should be string, value should be string, int, float, bool, for example `"{\"id\":\"123456789\",\"type\":1}"`. If the content-type is `application/json`, metadata should be key-value string, for example `{"id":"123456789", "type": 1}`
`parent_id`	string	Optional	uuid of the parent of the file
`frames`	[]FrameData	Optional	list of video frames to be uploaded

Upload video/audio — file, label are required and content-type must be multipart/form-data. If you use file, label, metadata, omit parameter frames.
Upload video frames — frames is required and content-type must be application/json. If you use frames, metadata, omit parameter file, label.

The `label` parameter

label says which kind of file is being uploaded.

`label`	Description
`video`	the video file
`audio`	the audio file

The `frames` parameter

Each entry in frames is a FrameData object:

Name	Type	Required	Description
`base64`	string	Optional	base64 encoded text of image data
`label`	string	Optional	label of the image as described at Label table
`index`	int	Optional	the index of this frame in the video
`metadata`	string_json	Optional	key-value, key should be string, value should be string, int, float, bool, for example `"{\"id\":\"123456789\",\"type\":1}"`. If the content-type is `application/json`, metadata should be key-value string, for example `{"id":"123456789", "type": 1}`

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/files \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-F 'file=@"videos/frames.mp4"'
-F 'label="video"'

Response

data.file_id is the id of the stored file.

JavaScript

{
  "data": {
    "file_id": string, // ID of the uploaded file in StoreDB
  },
  "errors": [
      {
        "code": string,
        "message": string,
        "detail": {
            "field": string, // optional, which parameter is invalid.
            ... // any other information that can be useful for client
        },
      },
      ... // other errors
  ]
}

On success the HTTP status code is 200 and data holds:

Name	Type	Description
`file_id`	string	ID of the uploaded file (UUID)

A successful upload comes back like this:

JSON

{
  "data": {
    "file_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8"
  }
}

Failure codes

In case of error, the data will be empty, and server sends following HTTP status code and error information:

HTTP code	Error code	Description
`400`	`invalid_parameter_exception`	Input parameter violates a constraint.
`400`	`request_time_too_skewed`	The X-TV-Timestamp header is expired, need a newer one.
`401`	`access_denied_exception`	You are not authorized to perform the action.
`404`	`image_not_found_exception`	The image ID is not found in DB.
`408`	`request_timeout_exception`	Request takes too long to process
`413`	`file_too_large_exception`	The input file size exceeds the allowed limit (15MB).
`429`	`rate_limit_exception`	The number of requests exceeded your throughput limit.
`500`	`internal_server_error`	Some unexpected error occurs while processing the request

The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.

PreviousDownload image NextDownload file