All Products
Search
Document Center

ApsaraVideo VOD:Request parameters

Last Updated:Jul 25, 2024

This topic describes the following request parameters of ApsaraVideo VOD API operations: PlayConfig, ReAuthInfo, UserData, SpriteSnapshotConfig, and EncryptConfig. This topic also provides examples on how to configure the parameters.

PlayConfig: specifies the custom configurations for media playback

Description

This parameter specifies the custom configurations for media playback. The value is a JSON string. You can configure playback settings for a specific streaming domain. The following table describes the fields in PlayConfig.

Field

Type

Required

Description

PlayDomain

String

No

The streaming domain. If you configure multiple origin domain names, you can specify a domain name to play the video. If the specified streaming domain does not exist, the default streaming domain configured for the storage address of the video is returned in the streaming URL. Example: "vod.test_domain".

XForwardedFor

String

No

The originating IP address of the client that initiates the request. This field is used to check whether the request is initiated from an IP address that is added to a review security group. For more information, see Security IP address preview. ApsaraVideo VOD can obtain the client IP address based on this field after a request passes through multiple proxy servers. To improve data security, the client IP address is encrypted by using AES/ECB/PKCS5Padding. To obtain the encryption key, submit a ticket.

Example: yqCD7Fp1uqChoVj/sl/p5Q==.

PreviewTime

String

No

The preview duration. Unit: seconds. The minimum value is 1. The maximum value is the total duration of the video. If you leave this field empty, the entire video is previewed. For more information about how to enable the preview feature, see Configure the preview feature.

MtsHlsUriToken

String

No

The MtsHlsUriToken that is generated by a token issuance service. You can specify this field to decrypt and play videos that are encrypted by using HTTP Live Streaming (HLS) encryption. This prevents decryption keys from being stolen. For more information, see HLS encryption.

EncryptType

String

No

The type of the encryption. You can specify this field to play videos that are not encrypted or videos that are encrypted in a specific type. Valid values:

  • Unencrypted: not encrypted

  • AliyunVoDEncryption: Alibaba Cloud proprietary cryptography

  • HLSEncryption: HLS encryption

Note

For more information about the playback URLs of encrypted streams, see Obtain a playback URL.

StorageClass

String

No

The storage class of the media asset. You can use this field to filter the playback streams of a specific storage class. Valid values:

  • By default, this field is left empty. An empty string specifies no filtering condition. If the storage class of the audio or video file is Standard, the playback URLs of all streams are returned. If the storage class of the media resources is not Standard, no playback URL is returned. If the storage class of the source file is not Standard, only playback URLs of the transcoded streams are returned, the playback URL of the original-quality stream is not returned.

  • All: all storage classes.

  • Standard: All media resources are stored as Standard objects.

  • IA: All media resources are stored as IA objects.

  • Archive: All media resources are stored as Archive objects.

  • ColdArchive: All media resources are stored as Cold Archive objects.

  • SourceIA: Only the source files are IA objects.

  • SourceArchive: Only the source files are Archive objects.

  • SourceColdArchive: Only the source files are Cold Archive objects.

  • Changing: The storage class of the media resources is being changed.

  • SourceChanging: The storage class of the source file is being changed.

Sample code

PlayConfig={
  "PlayDomain": "vod.test_domain",
  "XForwardedFor": "yqCD7Fp1uqChoVj/sl/p5Q==",
  "PreviewTime": "20",
  "MtsHlsUriToken": "yqCD7Fp1uqChoVjslp5Q",
  "StorageClass": "Standard"
}              

ReAuthInfo: specifies the configurations of CDN reauthentication

Description

This field specifies the configurations of CDN reauthentication for media playback. The value is a JSON string. After you enable the CDN reauthentication feature, you can use this field to specify the uid and rand fields for URL signing. The following table describes the fields in ReAuthInfo.

Field

Type

Required

Description

uid

String

No

The additional field. In most cases, the value is set to 0. You can specify a custom value for this field.

rand

String

No

The random number. In most cases, the value is set to 0. To generate a different URL each time the video is requested, you can use the UUID as the random number.

Sample code

ReAuthInfo={
  "uid": "12345",
  "rand": "abckljd"
}

UserData: specifies the custom configurations for media upload

Description

This field specifies the custom configurations for media upload, such as the callback configurations for event notifications. The value is a JSON string.

The following table describes the fields in UserData.

Field

Type

Required

Description

MessageCallback

String

No

The callback configurations for event notifications. The value is a JSON object. If you specify this field, the specified callback configurations take effect. Otherwise, the default callback configurations take effect. For more information, see Specify multiple callback URLs.

The following content describes the parameters:

  • CallbackType: the callback method. Valid values: http and mns.

  • CallbackURL: the HTTP callback URL. This parameter is required if you set CallbackType to http.

  • MNSQueueName: the name of the Message Service (MNS) queue. This parameter is required if you set CallbackType to mns.

  • MSSEndpoint: the endpoint of the MNS queue. This parameter is required if you set CallbackType to mns.

Examples:

  • HTTP callback: {"CallbackType":"http", "CallbackURL":"http://callback-host/addr"}

  • MNS callback: {"CallbackType":"mns","MNSQueueName":"vod-callback-bj","MNSEndpoint":"http://174809843091****.mns.cn-beijing.aliyuncs.com"}

Extend

String

No

The custom extended field, which is transparently transmitted during event callbacks. The value can be up to 512 bytes in length. The value is a JSON object.

Note

We recommend that you convert a value that contains special characters such as the dollar signs ($), forward slashes (/), or backslashes (\) to a Base64-encoded string.

AccelerateConfig

String

No

The configurations for upload acceleration. The value is a JSON object. Example: {"Type":"oss","Domain":"https://oss-accelerate.aliyuncs.com"}. Type specifies the acceleration method and its value can only be oss. Domain specifies the accelerated domain name. You can obtain the accelerated domain name from Regions and endpoints. By default, HTTPS is used.

Note

You can use the upload acceleration feature only after you submit an application to enable the feature. For more information about how to enable the upload acceleration feature and billing rules of the feature, see Upload acceleration.

Sample code

UserData={
  "MessageCallback": {
    "MNSEndpoint":"http://174809843091****.mns.cn-beijing.aliyuncs.com",
    "MNSQueueName":"vod-callback-bj",
    "CallbackType": "mns"
  },
  "Extend": {
    "localId": "xxx",
    "test": "www"
  },
  "AccelerateConfig": {
    "Type": "oss",
    "Domain": "https://oss-accelerate.aliyuncs.com"
  }
}
                        

EncryptConfig: specifies the configurations for HLS encryption

This field specifies the configurations for HLS encryption.

Field

Type

Required

Description

CipherText

String

Yes

The ciphertext key that is used to obtain the plaintext key. Set this parameter to the value of CiphertextBlob in the response to the GenerateKMSDataKey operation.

DecryptKeyUri

String

Yes

The key URI that is obtained based on the ciphertext key. The URI consists of the IP address of the decryption service and the value of Ciphertext.

The decryption service that you set up. For example, if the IP address of your decryption service is http://demo.aliyundoc.com, set this parameter to the following value:

http://demo.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3MTMt****

KeyServiceType

String

Yes

The type of the key service. Default value: KMS, which specifies Key Management Service of Alibaba Cloud.

SpriteSnapshotConfig: specifies the configurations for capturing image sprites

Field

Type

Required

Description

CellWidth

String

No

The width of the original snapshots that compose the image sprite. Default value: the width of a normal snapshot. Unit: pixels.

CellHeight

String

No

The height of the original snapshots that compose the image sprite. Default value: the height of a normal snapshot. Unit: pixels.

Padding

String

No

The padding of the original snapshots that compose the image sprite. Default value: 0. Unit: pixels.

Margin

String

No

The margin of the original snapshots that compose the image sprite. Default value: 0. Unit: pixels.

Color

String

No

The background color of the image sprite. Default value: Black.

Columns

String

No

The number of columns for the original snapshots that compose the image sprite. Valid values: [1,10000]. Default value: 10.

Lines

String

No

The number of rows for the original snapshots that compose the image sprite. Valid values: [1,10000]. Default value: 10.

KeepCellPic

String

No

Specifies whether to retain the original snapshots that compose the image sprite. Valid values:

  • keep

  • delete

Default value: keep.

Note

If you want to set all the fields in SpriteSnapshotConfig to the corresponding default values, specify an empty JSON string for SpriteSnapshotConfig.