Create clips from your videos

Developer Guide: Creating Clips from Your Videos

This guide aims to assist developers in using the Visionular API to create clips from live video streams. By following this guide, you will learn how to retrieve the assetID of a live stream, create video clips, obtain playback links for the clips, and download the clips in MP4 format. This functionality is particularly useful for users who want to capture highlights from live content, such as news reports, sports replays, or educational materials.

Step-by-Step Guide

Step 1: Retrieve `assetID`

First, you need to obtain the assetID of the live stream. This can be achieved by calling the List Assets API, which returns a list of all assets associated with your account. You can filter the results based on the live_stream_id.

API Description: List Assets

Method: GET
URL: /video-streams/v1/assets

Parameters:

live_stream_id (query parameter): Filters the response to return assets for this specific live stream.
limit (query parameter, default: 25): Number of items returned per page.
page (query parameter): Page number of the returned results.

Example Request:

GET /video-streams/v1/assets?live_stream_id={LIVE_STREAM_ID}
Host: api.visionular.com
Authorization: Bearer {your_access_token}

Response Fields:

code (integer): Response status code, 0 indicates success.
data (array): An array of asset information, each element represents an asset.
- asset_id (string): Unique identifier of the asset.
- status (string): Status of the asset (e.g., ready).
- live_stream_id (string): Associated live stream ID.
- playback_ids (array): An array of playback identifiers.
  - policy (string): Playback policy.
  - id (string): Playback identifier.
- user_metadata (string): User metadata.
- mp4_support (string): MP4 support status.
- created_at (integer): Timestamp of asset creation.

Example Response:

{
  "code": 0,
  "data": [
    {
      "asset_id": "202405-MTkwNmI5YjQyMmUyMjQyYWYwNGMxZWY4Y2M3MTM5ZTg",
      "status": "ready",
      "duration": 0,
      "live_stream_id": "202405-YTlhNGJhY2VmMDAyZjU4NTA3NTYwZjg2MmFmYzRhYTE",
      "playback_ids": [
        {
          "policy": "public",
          "id": "202405-ZDFmY2Q4YzQ5YmM2ODRjOWJkNTExM2JlN2YyZmI3NDk"
        }
      ],
      "user_metadata": "demo",
      "mp4_support": "capped-1080p",
      "created_at": 1715340816
    }
  ],
  "message": "success",
  "request_id": "1a39a89c-c743-437a-aeb8-4e84e0746343"
}

In the response, the asset_id field is your assetID. Note this value for subsequent steps.

Step 2: Create Clips

Next, use the Clip Asset API to create a video clip. This API requires the assetID, start time, and end time, and it returns details about the created clip.

API Description: Clip Asset

Method: POST
URL: /video-streams/v1/video/clip

Request Body Fields:

asset_id (string, required): The ID of the asset to clip.
start_time (integer, required): Start time of the clip in seconds.
end_time (integer, required): End time of the clip in seconds.

Headers:

Content-Type: application/json
Authorization (required): Use Bearer Token for authentication.

Example Request:

{
  "asset_id": "202405-MTkwNmI5YjQyMmUyMjQyYWYwNGMxZWY4Y2M3MTM5ZTg",
  "start_time": 30,
  "end_time": 90
}

Response Fields:

code (integer): Response status code, 0 indicates success.
data (object): Contains details about the created video clip.
- asset_id (string): Unique identifier of the video clip.
- source_asset_id (string): Source asset ID.
- status (string): Status of the video clip (e.g., preparing).
- duration (integer): Duration of the video clip in seconds.
- live_stream_id (string): Associated live stream ID.
- playback_ids (array): An array of playback identifiers.
  - policy (string): Playback policy.
  - id (string): Playback identifier.
- user_metadata (string): User metadata.

Example Response:

{
  "code": 0,
  "data": {
    "asset_id": "202410-Y2FjMTE4OGJlMWY1NDQzMDEyOTVkZWZjNzRkY2JiZjc",
    "source_asset_id": "202405-YTlhNGJhY2VmMDAyZjU4NTA3NTYwZjg2MmFmYzRhYTE",
    "status": "preparing",
    "duration": 60,
    "live_stream_id": "202405-YTlhNGJhY2VmMDAyZjU4NTA3NTYwZjg2MmFmYzRhYTE",
    "playback_ids": [
      {
        "policy": "public",
        "id": "202405-ZDFmY2Q4YzQ5YmM2ODRjOWJkNTExM2JlN2YyZmI3NDk"
      }
    ],
    "user_metadata": "demo"
  },
  "message": "success",
  "request_id": "be66104c-af6c-48a0-b19c-95170e7768dd"
}

The playback_id field from the response will be used in the subsequent steps.

Step 3: Obtain Playback Link

Using the playback_id obtained from the second step, you can assemble the playback URL for the clip.

Playback URL Format:

https://stream.visionular.com/{PLAYBACK_ID}.m3u8

For example:

https://stream.visionular.com/202405-Y2FjMTE4OGJlMWY1NDQzMDEyOTVkZWZjNzRkY2JiZjc.m3u8

Step 4: Download MP4 File

Finally, you can assemble the MP4 download URL using the playback_id to download the clip in MP4 format.

MP4 Download URL Format:

https://stream.visionular.com/{PLAYBACK_ID}/capped-1080p.mp4?download={FILE_NAME}

For example:

https://stream.visionular.com/202405-ZDFmY2Q4YzQ5YmM2ODRjOWJkNTExM2JlN2YyZmI3NDk/capped-1080p.mp4?download=clip.mp4

Visionular