DocsICP FilingConsole
官方文档
首页

Request parameter descriptions

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes the parameters and provides configuration examples for PlayConfig, ReAuthInfo, UserData, SpriteSnapshotConfig, and EncryptConfig in ApsaraVideo VOD APIs.

Custom playback settings: PlayConfig

Parameter descriptions

A JSON string that specifies custom settings for media playback. You can use this parameter to specify a domain name for playback. The following fields are supported:

Field name

Type

Required

Description

PlayDomain

String

No

The domain name for playback. If you configure multiple origin fetch domain names, you can specify one of them to play the current video. If the specified domain name does not exist, the playback URL of the default domain name for the video storage is returned. Example: "vod.test_domain".

XForwardedFor

String

No

The originating IP address of the client that initiates the request. This can be used in scenarios such as authenticating secure IP addresses. ApsaraVideo VOD can obtain the originating client IP address based on this field after a request passes through multiple proxy servers. To ensure data security, this IP address is encrypted using the AES/ECB/PKCS5Padding method. To obtain the encryption key, submit a ticket. The ticket is processed by the ApsaraVideo VOD service.

Example: yqCD7Fp1uqChoVj/sl/p5Q==

PreviewTime

String

No

The preview duration for video-on-demand, in seconds. The minimum value is 1. The maximum value is the total duration of the video. If you do not specify this parameter, the entire video can be played. To enable the preview feature, see Preview videos.

MtsHlsUriToken

String

No

The MtsHlsUriToken generated by your token service. This parameter applies to the playback of videos that use HLS encryption. It protects your decryption key from being stolen. For more information, see HLS encryption.

EncryptType

String

No

The encryption type. You can use this parameter to filter and play unencrypted or encrypted streams. Valid values:

  • Unencrypted: The data is not encrypted.

  • AliyunVoDEncryption: Alibaba Cloud proprietary cryptography.

  • HLSEncryption: HLS encryption.

Note

For information about the usage and limits of encrypted stream URLs, see Obtain URLs in advance through event notifications.

StorageClass

String

No

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

  • Empty: The default value. No filtering is performed. If the audio or video file is in the Standard storage class, the playback stream is returned. If the media asset is in a non-Standard storage class, the API does not return a playback stream. If the source file is in a non-Standard storage class, the API returns only transcoded streams, not the original quality stream.

  • All: All types.

  • Standard: Standard.

  • IA: Infrequent Access (IA) for media assets.

  • Archive: Archive for media assets.

  • ColdArchive: Cold Archive for media assets.

  • SourceIA: Infrequent Access storage for source files.

  • SourceArchive: Archive for source files.

  • SourceColdArchive: Cold Archive for source files.

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

  • SourceChanging: The source file is changing.

Configuration example

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

CDN reauthentication settings: ReAuthInfo

Parameter descriptions

A JSON string that specifies the parameters for CDN reauthentication during media playback. If you enable CDN reauthentication, you can use this parameter to set the `uid` and `rand` fields for the signed URL. The following fields are supported:

Field name

Type

Required

Description

uid

String

No

An additional parameter. The default value is 0. You can customize this parameter.

rand

String

No

A random number. The default value is 0. To ensure that a unique URL is generated each time, you can use a UUID or another method to generate a random number.

Configuration example

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

Custom upload settings: UserData

Parameter descriptions

A JSON string that specifies custom settings for media uploads, such as message callbacks.

The following fields are supported:

Field name

Type

Required

Description

MessageCallback

String

No

The message callback settings. The data type is a JSON object. If you specify this parameter, these event notification settings are used. Otherwise, the global event notification settings are used. For more information, see Configure multiple webhooks.

Parameter descriptions:

  • CallbackType: The callback method. Valid values are http and mns.

  • CallbackURL: The HTTP webhook address. This parameter is required when CallbackType is set to http.

  • MNSQueueName: The name of the MNS queue. This parameter is required when CallbackType is set to mns.

  • MNSEndpoint: The endpoint of the MNS queue. This parameter is required when CallbackType is set to mns.

Example values:

  • 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

A custom extension field. This field is passed through and returned in the callback. The maximum length is 512 bytes. The data type is a JSON object.

Note

Avoid using special characters, such as the dollar sign ($), forward slash (/), and backslash (\\), in the extension field. If you must use them, Base64-encode the parameter value and Base64-decode it when you retrieve it.

AccelerateConfig

String

No

The upload acceleration settings. The data type is a JSON object. Example: {"Type":"oss","Domain":"https://oss-accelerate.aliyuncs.com"}. `Type` is the acceleration method (only `oss` is supported). `Domain` is the accelerated domain name, which corresponds to an OSS region and endpoint. The default protocol is HTTPS.

Note

You must request to activate the upload acceleration feature before you can use it. For information about how to activate this feature and its billing, see Upload acceleration.

Configuration example

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"
  }
}

Encryption configuration: EncryptConfig

Specifies the standard encryption configuration.

Field name

Type

Required

Description

CipherText

String

Yes

The ciphertext of the data key. It is used to obtain the plaintext data key. Set this parameter to the CiphertextBlob value returned by the GenerateDataKey operation of KMS.

DecryptKeyUri

String

Yes

The URI that is used to obtain the decryption key based on the ciphertext. The key URI is a combination of the decryption service address and the Ciphertext value.

You must build your own decryption service. For example, if your decryption service address is http://demo.aliyundoc.com, set this parameter as follows:

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

KeyServiceType

String

Yes

The type of key service. The default value is `KMS`, which indicates Alibaba Cloud Key Management Service (KMS).

Sprite snapshot configuration: SpriteSnapshotConfig

Field name

Type

Required

Description

CellWidth

String

No

The width of a sub-image in the sprite. The default value is the width of the snapshot output. Unit: px.

CellHeight

String

No

The height of a sub-image in the sprite. The default value is the height of the snapshot output. Unit: px.

Padding

String

No

The padding of a sub-image. The default value is 0. Unit: px.

Margin

String

No

The margin of a sub-image. The default value is 0. Unit: px.

Color

String

No

The background color of the sprite. The default value is Black.

Columns

String

No

The number of columns of sub-images. Valid values: [1, 10000]. Default value: 10.

Lines

String

No

The number of rows of sub-images. Valid values: [1, 10000]. Default value: 10.

KeepCellPic

String

No

Specifies whether to retain the sub-images. Valid values:

  • keep: Retain.

  • delete: Delete.

Default value: keep.

Note

If you want to use the default values for all parameters in SpriteSnapshotConfig, you can pass an empty JSON string: {}.

Previous：Basic data typesNext：Parameters for media processing