Create a VOD encoding

To create a VOD encoding request, it is necessary to prepare certain resources beforehand, such as subtitles, a video file, and a watermark (if needed). Before submitting the encoding request, ensuring these required resources are available is important. If they are not already available, they must be uploaded to the Video library first. Once uploaded, their corresponding IDs can be obtained and used in the VOD encoding request. Uploading files to the Video library can be completed by following the steps provided.

Here's a simple diagram of the process:

Once you have ensured all the required resources exist and have obtained their corresponding IDs, you can create the VOD encoding request using those IDs. The request can include a subtitle, queue type, metadata, security control, privacy settings, watermarks, domain control, geo control, DRM, and schedule.

POST /bv/cms/v1/vods

{
  "name":"string",
  "profile_set_id":"string",
  "source":{
    "type":"SOURCE_TYPE_UNSPECIFIED",
    "library":{
      "video":{
        "id":"string"
      },
      "subtitles":[
        {
          "id":"string",
          "name":"string",
          "code":"string",
          "display":"string"
        }
      ]
    },
    "cloud_storage":{
      "id":"string",
      "file_path":"string",
      "subtitles":[
        {
          "id":"string",
          "name":"string",
          "code":"string",
          "display":"string"
        }
      ]
    }
  },
  "queue":"QUEUE_STANDARD",
  "pte":{
    "profile":"PTE_PROFILE_UNSPECIFIED"
  },
  "metadata":{
    "short_description":"string",
    "long_description":"string",
    "labels":[
      {
        "name":"string"
      }
    ]
  },
  "security":{
    "privacy":{
      "type":"SECURITY_PRIVACY_TYPE_UNSPECIFIED",
      "token":{
        "device_limit":0
      }
    },
    "watermark":{
      "enabled":true,
      "type":"WATERMARK_TYPE_UNSPECIFIED",
      "position":"WATERMARK_POSITION_UNSPECIFIED",
      "image":{
        "library_id":"string"
      }
    },
    "domain_control":{
      "enabled":true,
      "domains":[
        "string"
      ]
    },
    "protection":{
      "type":"PROTECTION_TYPE_UNSPECIFIED"
    },
    "geo_control":[
      "string"
    ]
  },
  "schedule":{
    "enable":true,
    "start_time":"2019-08-24T14:15:22Z",
    "end_time":"2019-08-24T14:15:22Z"
  },
  "export":{
    "cloud_storage":{
      "id":"string"
    }
  }
}

The followings introduce each important attribute in more detail:

Source

When requesting a VOD encoding to BlendVision, we need to specify the source and subtitles for the media file.

1. Determine the source type

The source type can be one of the following:

SOURCE_TYPE_LIBRARY: if the source is uploaded from a local file
SOURCE_TYPE_CLOUD_STORAGE: if the source is copied from specified cloud storage.

2. Create the source object

Based on the source type, create the source object accordingly.

If the source type is SOURCE_TYPE_LIBRARY, create the source object as follows:

"source":{
  "type":"SOURCE_TYPE_LIBRARY",
  "library":{
    "video":{
      "id":"your_video_id_in_library"
    }
  }
}

If the source type is SOURCE_TYPE_CLOUD_STORAGE, create the source object as follows:

"source":{
  "type":"SOURCE_TYPE_CLOUD_STORAGE",
  "cloud_storage":{
    "id":"your_cloud_storage_id",
    "file_path":"/path/to/cloud/storage/file.mp4"
  }
}

3. Specify subtitles for the media file

Subtitles must be uploaded using /bv/cms/v1/library/files:upload API first, and the uploaded_data.id from the response should be used to specify the subtitle in the source object. Here's an example of how to specify subtitles:

"source":{
  "type":"SOURCE_TYPE_LIBRARY",
  "library":{
    "video":{
      "id":"6d706ee2-a1c2-41fe-9a68-b8ef23604f1a"
    },
    "subtitles":[
      {
        "id":"your_subtitles_id",
        "name":"English",
        "code":"en",
        "display":"true"
      }
    ]
  }
}

Queue

You can select the standard or faster queue for encoding jobs by setting the "queue" field to QUEUE_STANDARD or QUEUE_PRIORITY. Noted if you select QUEUE_PRIORITY to process encoding jobs, you will be charged a higher fee.

PTE

You can enable PTE by setting the profile field in the pte object to PTE_PROFILE_HIGH for encoding jobs. PTE will be applied to every profile within the ProfileSet you choose.

Metadata

You can provide additional information about a VOD, which can be used to classify, organize, and search for VODs based on their properties.

1. Short description

The short_description field is a string that provides a brief summary of the VOD. It should not exceed 100 characters, including letters, numbers, spaces, punctuations, and special symbols. This field is typically used to provide a quick overview of the VOD.

2. Long description

The long_description field is a string that provides a more detailed description of the VOD. It should not exceed 200 characters, including letters, numbers, spaces, punctuations, and special symbols. This field can be used to provide additional context, background information, or other details.

3. Labels

The labels field is an array of objects that provide additional metadata about the VOD. Each label object contains a name field, which is a string that specifies the name of the label. Labels can be used to categorize and organize VODs based on their properties and can be used to facilitate search and filtering operations. The maximum length of each label is 20 characters, and a maximum of 20 labels can be assigned to a VOD.

Privacy

To make the VOD become a private one, you can enable privacy control to protect your content using redeem codes by setting the type field in the privacy object to SECURITY_PRIVACY_TYPE_TOKEN and specifying the number of device limitations to the device_limit field in the token object.

Here's an example:

"privacy":{
  "type":"SECURITY_PRIVACY_TYPE_TOKEN",
  "token":{
    "device_limit":100
  }
}

Watermark

To enable watermarking and specify the type and position, set the enabled field to true and specify the type and position fields with appropriate values.

For example, if you want to use the WATERMARK_TYPE_IMAGE type and position it to the top-right corner of the image; the request body could be updated as follows:

"watermark":{
  "enabled":true,
  "type":"WATERMARK_TYPE_IMAGE",
  "position":"WATERMARK_POSITION_TOP_RIGHT",
  "image":{
    "library_id":"your-library-id-here"
  }
}

Note that if the type is WATERMARK_TYPE_IMAGE, the library_id field in the image object is required and should be set to the ID of the library containing the watermark image.

Alternatively, if you want to use the WATERMARK_TYPE_USER_ID type, the request body could be updated as follows:

"watermark":{
  "enabled":true,
  "type":"WATERMARK_TYPE_USER_ID",
  "position":"WATERMARK_POSITION_RANDOM"
}

Domain Control

You can enable the domain control feature to protect your content delivery and restrict access to specific domains. This feature allows you to specify a list of allowed domains and ensure that your content is only delivered to those domains.

For example, if you want to restrict the delivery of your content to only two domains: example.com and test.com. You can enable the domain control feature and specify these domains in the request body like this:

"domain_control":{
  "enabled":true,
  "domains":[
    "example.com",
    "test.com"
  ]
}

DRM

By setting the type field in the protection object to PROTECTION_TYPE_DRM, you can enable DRM for the VOD, providing greater security and protection against unauthorized access and distribution.

Schedule

By default, the content is always available; however, you can limit the availability of your content for a certain period by setting the start and end time.

If you want to schedule the availability, you can use the schedule request body with the following options:

1. enable

This is a boolean value that determines whether the scheduling is enabled.

2. start_time and end_time

The start_time and end_time specify the date and time when the content will become available and when it will no longer be available, respectively. The format for both start_time and end_time is ISO 8601, which is YYYY-MM-DDTHH:MM:SSZ.

The time zone is automatically detected and set to the local time zone of the user's location. This means that if a user is located in a different time zone than the server, the start_time and end_time will be automatically adjusted to match the user's local time zone.

Here is an example of a request body that schedules a video for playback from August 24th, 2023 at 2:15:22 PM UTC to August 31st, 2023 at 2:15:22 PM UTC:

"schedule":{
  "enable":true,
  "start_time":"2023-08-24T14:15:22Z",
  "end_time":"2023-08-31T14:15:22Z"
}

If you want to edit a scheduled video's custom date and time, you can do so before the start or end time has passed. After that, the start and end times become non-editable.

Before Scheduled Start Time: If the scheduled start time has not yet been reached, you can edit both the start and end times.
Before Scheduled End Time: If the scheduled end time has not yet been reached, you can edit the end time.

更新 2023年05月29日 08:01

Encoding