Creating coub

A coub consists of two parts: the video sample and the audio track.

To create a coub via API you need to:

  1. Initialize the upload and get the id for the upload;
  2. Add a video for the coub;
  3. Add an audio track for the coub;
  4. Finalize the coub.

1. Initialize upload

HTTP POST /api/v2/coubs/init_upload

Request parameters:

None.

Response format:

  • id (integer) — the id of the upload
  • permalink (string) — the permalink of upload

Response example:

{
  "permalink": permalink,
  "id": ID
}

2. Add a video for the coub

HTTP POST /api/v2/coubs/:id/upload_video

Request parameters:

The Content-Type header of the request should be set to an appropriate value.

Content-Type: video/flv

The request body should contain bytes of the video file. We support most of modern video and audio codecs. However, H.264 is recommended for video and AAC is for audio.

The video length is limited to 10 seconds, the file size — to 400MB.

Response format:

  • status (string) — "ok" if the request successed;

or

  • message (string) — the text of an error which occured during uploading.

Response example:

{ "status": "ok" }
{ message: "Video files should be at least 300x100" }

3. Add an audio for the coub

HTTP POST /api/v2/coubs/:id/upload_audio

Request parameters:

The Content-Type header of the request should be set to an appropriate value.

Content-Type: audio/mpeg

The request body should contain bytes of the audio file. The file should be encoded with the MP3 codec.

Response format:

  • status (string) — "ok" if the request successed;

or

  • message (string) — the text of an error which occured during uploading.

Response example:

{ "status": "ok" }
{ message: "Audio file not recognized" }

4. Finalizing upload

Calling this endpoint means that all the editing is finished, and we can generate the final version for this coub.

HTTP POST /api/v2/coubs/:id/finalize_upload

Request parameters:

  • sound_enabled (boolean) — enables or disables sound for the coub; required field;
  • title (string) – the title of the coub; required field;
  • original_visibility_type (string) – should be sound to one of the values: public, friends, unlisted, private; required field;
  • tags (string) — the tags list separated with the comma.

Request parameters example:

sound_enabled=true&title=test&original_visibility_type=public&tags=test,ok,wow

Response format:

  • status (string) — "ok" if the request successed, "fail" if something went wrong;
  • reason (string) — the error message text (optional).

Response example:

{ "status": "ok" }
{ status: "fail", reason: "Wrong visibility type" }

If all is well the finalization process starts. It usually takes 30–180 seconds.

Getting finalizing status

This endpoint returns the actual finalization status for the recently finalized coub.

HTTP GET /api/v2/coubs/:id/finalize_status

Response format:

  • done (boolean) — whether the coub finalizing is in the process;
  • percent_done (integer) – the estimated percent of the completed work.

Response example:

{"done": "false", "percent_done": 40}
{"done": "true", "percent_done": 100}

When the coub is created you can get all needed coub's info via the Coubs API endpoint.