RICHKA Web API

RICHKA provides two interfaces with GUI and Web API to enables users to easily create video data with setting images, videos and texts and generating videos. In this post, we describe the Web API whose architecture conforms to the general REST architecture. It enables users to integrate the primary features of RICHKA into their systems such as smartphone application to generate videos with using the photo album.

The main functions of Web API are below, and they are built with Django REST Framework.

• Authenticate API clients and publish API tokens
• Get list of projects/videos
• Create projects / videos
• Set images / videos / texts to scenes of videos
• Generate video files

The basic sequence diagram to generate videos is below.

To call Web API, API clients need to set tokens TOKEN_AUTH in every request. The tokens are published with sending HTTP POST to /api/v1/api-token-auth/ with the account information. API clients should store the tokens into their database to suppress this API call every time.

curl -X POST https://API_HOST/api/v1/accounts/login/ \
     -H 'Content-Type: application/json' \
     -d '{
       "email": "USER_EMAIL",
       "password": "USER_PASSWORD"
     }'

A new project directory is created with sending HTTP POST to /api/v1/projects/ as below.

curl -X POST https://API_HOST/api/v1/projects/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "New Project",
       "is_shared": true
     }'

The ID of the created project PROJECT_ID is returned to the clients. The detail information of the project can be obtained with sending HTTP GET to /v1/projects/PROJECT_ID/.

API clients can get a list of available template IDs TEMPLATE_ID with sending HTTP GET to /api/v1/template_groups/.

curl -X GET https://API_HOST/api/v1/template_groups/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'Content-Type: application/json'

A new video data is created with sending HTTP POST to /api/v1/videos/ with specifying the created project id PROJECT_ID and the selected video template TEMPLATE_ID. The ID of the created video data VIDEO_ID is returned to the clients.

curl -X POST https://API_HOST/api/v1/videos/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "your video title",
       "project_id": "PROJECT_ID",
       "template_id": TEMPLATE_ID
     }'

For 1st step, API clients need to upload the image/video files to be available in the video data with VIDEO_ID. Then IMAGE_NAME_1 and IMAGE_NAME_2 are returned to the clients.

curl -X POST https://API_HOST/api/v1/videos/VIDEO_ID/images/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
     -F 'files[]=@/path/to/image/1.png' \
     -F 'files[]=@/path/to/image/2.jpeg'

After uploading the file contents, API clients can set the images into scenes of the video data with using the identifiers IMAGE_NAME_1 and IMAGE_NAME_2.

curl -X PUT https://API_HOST/api/v1/videos/VIDEO_ID/ \
  -H 'Authorization: Token TOKEN_AUTH' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New video'\''s name",
    "bgm_file": BGM_ID,
    "memo": "New Memo",
    "slides": [
	{
	    "index": 0,
	    "text": "テキスト",
	    "image_name": "IMAGE_NAME_1"
	},
	{
	    "index": 1,
	    "text": "テキスト",
	    "image_name": "IMAGE_NAME_2"
	}
    ]
}'

After the scenes have been set up, API clients can request to start the video generation with video servers.

curl -X POST https://API_HOST/api/v1/videos/VIDEO_ID/generate/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'Content-Type: application/json'

When the video generation has been done, a Webhook URL registered in the account setting page beforehand will be called back with sending VIDEO_ID.

{
  video_id: VIDEO_ID,
  user_id: xxxxx,
  time: 2020-01-01 01:02:03,
  webhook_id: 1234,
  type: webhook
}

API clients can get the downloadable S3 URLs with sending HTTP GET with /api/v1/videos/VIDEO_ID/.

curl -X GET https://API_HOST/api/v1/videos/VIDEO_ID/ \
     -H 'Authorization: Token TOKEN_AUTH' \
     -H 'Content-Type: application/json'