Basic data types of the ApsaraVideo VOD API - ApsaraVideo VOD

This topic describes the basic data types of the ApsaraVideo VOD API.

Basic information about media assets

Video: Audio and video information

Name	Type	Description
VideoId	String	The ID of the audio or video file.
Title	String	The title of the audio or video file.
Description	String	The description of the audio or video file.
Duration	Float	The duration of the audio or video file. Unit: seconds.
CoverURL	String	The thumbnail URL of the audio or video file.
Status	String	The status of the audio or video file. For more information, see Status: Audio and video status.
CreationTime	String	The time when the audio or video file was created. The time is in UTC.
Size	Long	The size of the source audio or video file. Unit: bytes.
Snapshots	String[]	An array of video snapshot URLs.
CateId	Long	The category ID of the audio or video file.
CateName	String	The category name of the audio or video file.
Tags	String	The tags of the audio or video file. Separate multiple tags with commas (,).
TemplateGroupId	String	The ID of the transcoding template group used for transcoding the audio or video file.
StorageLocation	String	The storage address of the audio or video file.
AppId	String	The application ID.

Status: Audio and video status

Value	Description	Notes
Uploading	Uploading	This is the initial status of an audio or video file. It indicates that the file is being uploaded. If your audio or video file remains in the Uploading status for a long time, see Why is my uploaded file always in the Uploading status?. You can only delete audio or video files in this state. You Cannot perform other operations on them, such as transcoding, snapshot capture, or media asset review.
UploadFail	Upload failed	An upload may fail due to network issues or source file corruption. We recommend that you retry the upload or upload a different source file. When you use resumable upload, the audio or video file will not enter this status because it is not possible to determine whether the upload has failed. You can only delete audio or video files that are in this status. You Cannot perform other operations on them, such as transcoding, snapshot capture, or review.
UploadSucc	Uploaded	If a video is uploaded but the default transcoding process is skipped for business or other reasons, or if a no-transcoding template group is used for a source file that is not in MP4, FLV, M3U8, MP3, or WEBM format, no valid playback streams are generated. In this case, the video is in the Uploaded status. After the video is transcoded and a valid playback stream is generated, its status changes to Normal. You Can perform operations such as transcoding, snapshot capture, or review on audio and video files in this status.
Transcoding	Transcoding	Audio and video files in this status are being transcoded. When a video is being transcoded for the first time, no valid playback streams are available, and you cannot obtain playback URLs by calling API operations. You can determine the transcoding status from event notifications for transcoding completion, such as Single Definition Transcoding Complete or All Definitions Transcoding Complete.
TranscodeFail	Transcoding failed	Transcoding failures are usually caused by errors in the source file. You can obtain the ErrorMessage from the StreamTranscodeComplete or TranscodeComplete event notification, or see Transcoding FAQ to troubleshoot the failure.
Checking	Reviewing	If you enable the Review Before Release feature in ApsaraVideo VOD Console >Review Management >Review Settings, an audio or video file automatically enters the review process after it is uploaded to ApsaraVideo VOD and successfully transcoded. The status of the file is then marked as Reviewing. You must then initiate a manual review. Otherwise, the file remains in the Reviewing status. You can play audio and video files in this status only in the ApsaraVideo VOD console or using a secure IP address for review. You cannot obtain playback URLs for these files using an API or SDK. However, you can still play them using valid playback URLs that have been exposed. You can perform operations such as transcoding and snapshot capture on audio and video files in this status. Note Note that the Reviewing status for a media asset (which you can view in the Status column under ApsaraVideo VOD Console >Media Files > Audio/Video) is different from the Reviewing status for a machine-assisted moderation job (which you can view in the Machine-assisted Moderation Status column under ApsaraVideo VOD Console > Review Management > Content Moderation). The Reviewing status for a machine-assisted moderation job describes only the status of that job, whereas the Reviewing status for a media asset describes the status of both machine-assisted and manual review jobs.
Blocked	Blocked	You can play audio and video files in this status only in the ApsaraVideo VOD console or using a secure IP address for review. You cannot obtain playback URLs for these files using an API or SDK. However, you can still play them using valid playback URLs that have been exposed. You can only delete audio or video files in this status. You Cannot perform other operations on them, such as transcoding, snapshot capture, or media asset review.
Normal	Normal	An audio or video file is in the Normal status if at least one valid playback stream exists. You Can perform all operations, such as transcoding, snapshot capture, review, and playback, on audio or video files that are in this status.
ProduceFail	Production failed	The video failed to be produced by online editing. When you use the online editing feature of ApsaraVideo VOD to produce videos, make sure that all media assets used for production are in the Normal status. Otherwise, video production may fail.

ImageInfo: Image information

Name	Type	Description
ImageId	String	The ID of the image.
URL	String	The URL of the image. If an accelerated domain name is configured, a CDN URL is returned. Otherwise, an OSS URL is returned.
Title	String	The title of the image.
Tags	String	The tags of the image.
ImageType	String	The type of the image.
CateId	Long	The category ID.
CateName	String	The category name.
Description	String	The description.
StorageLocation	String	The storage address of the file.
Mezzanine	Mezzanine	The source information of the image.
CreationTime	String	The time when the image was created. The time is in UTC.
Status	String	The status of the image. For more information, see Status: Image status.
AppId	String	The application ID.

Status: Image status

Value	Description	Notes
Uploading	Uploading	This is the initial status of an image. It indicates that the image is being uploaded. If your image remains in the Uploading status for a long time, see Why is my uploaded file always in the Uploading status?.
UploadFail	Upload failed	An upload may fail due to network issues or source file corruption. We recommend that you retry the upload or upload a different source file.
Normal	Normal	The image is uploaded.

AttachedMediaInfo: Auxiliary media asset information

Name	Type	Description
MediaId	String	The ID of the auxiliary media asset.
URL	String	The URL of the auxiliary media asset. If an accelerated domain name is configured, a CDN URL is returned. Otherwise, an OSS URL is returned.
Title	String	The title.
Tags	String	The tags.
Type	String	The type of the auxiliary media asset.
Categories	Category[]	The list of categories.
Description	String	The description.
StorageLocation	String	The storage address of the file.
CreationTime	String	The time when the auxiliary media asset was created. The time is in UTC.
ModificationTime	String	The time when the auxiliary media asset was last updated. The time is in UTC.
Status	String	The status of the auxiliary media asset. For more information, see Status: Auxiliary media asset status.
AppId	String	The application ID.

Status: Auxiliary media asset status

Value	Description	Notes
Uploading	Uploading	The initial status. It indicates that the auxiliary media asset is being uploaded.
Normal	Normal	The auxiliary media asset is uploaded.
UploadFail	Failed	The auxiliary media asset failed to be uploaded.

Media resource file information

Mezzanine: Audio and video source file information

Name	Type	Description
VideoId	String	The video ID.
FileName	String	The name of the file.
Duration	String	The duration of the file. Unit: seconds.
Status	String	The status of the source file. For more information, see Status: Audio and video source file status.
CreationTime	String	The time when the file was created. The time is in UTC.
Height	Long	The height of the file. Unit: pixel.
Width	Long	The width of the file. Unit: pixel.
Fps	String	The frame rate of the file, in frames per second.
FileURL	String	The URL of the file.
Bitrate	String	The bitrate of the file. Unit: Kbit/s.
Size	Long	The size of the file. Unit: bytes.
OutputType	String	The type of the output file. Valid values: oss: the address of the origin server. cdn: the accelerated address.
VideoStreamList	VideoStream[]	The list of video stream information.
AudioStreamList	AudioStream[]	The list of audio stream information.

VideoStream: Video stream information

Name	Type	Description
Index	String	The sequence number of the video stream. This identifies the position of the video stream within the entire media stream.
CodecName	String	The short name of the encoding format.
CodecLongName	String	The long name of the encoding format.
Profile	String	The codec profile.
CodecTimeBase	String	The codec time base.
CodecTagString	String	The tag string of the encoding format.
CodecTag	String	The tag of the encoding format.
Width	Long	The width of the video resolution.
Height	Long	The height of the video resolution.
HasBFrames	String	Indicates whether B-frames exist.
Sar	String	The sample aspect ratio (SAR).
Dar	String	The display aspect ratio (DAR).
PixFmt	String	The pixel format.
Level	String	The encoding level.
Fps	String	The target frame rate.
AvgFPS	String	The average frame rate.
Timebase	String	The time base.
StartTime	String	The start time.
Duration	String	The duration.
NumFrames	String	The total number of frames.
Lang	String	The language.
Rotate	String	The rotation angle of the video. Valid values: [0, 360).

AudioStream: Audio stream information

Name	Type	Description
Index	String	The sequence number of the audio stream. This identifies the position of the audio stream within the entire media stream.
CodecName	String	The short name of the encoding format.
CodecLongName	String	The long name of the encoding format.
CodecTimeBase	String	The codec time base.
CodecTagString	String	The tag string of the encoding format.
CodecTag	String	The tag of the encoding format.
SampleFmt	String	The sampling format.
SampleRate	String	The sample rate.
Channels	String	The number of sound channels.
ChannelLayout	String	The layout of the sound channels.
Timebase	String	The time base.
StartTime	String	The start time.
Duration	String	The duration.
Bitrate	String	The bitrate.
NumFrames	String	The total number of frames.
Lang	String	The language.

Status: Audio and video source file status

Value	Description	Remarks
Uploading	Uploading	The initial status of the file. It indicates that the file is being uploaded.
Normal	Normal	The file is uploaded.
UploadFail	Failed	The file failed to be uploaded.
Deleted	Deleted	The file is deleted.

Mezzanine: Image source file information

Name	Type	Description
FileURL	String	The OSS URL of the image.
OriginalFileName	String	The name of the uploaded file.
FileSize	Long	The size of the file. Unit: bytes.
Width	Integer	The width of the image. Unit: pixel.
Height	Integer	The height of the image. Unit: pixel.

Batch upload from URLs

URLUploadInfo: URL upload information

Name	Type	Description
JobId	String	The job ID.
UploadURL	String	The upload URL.
MediaId	String	The ID of the uploaded video.
FileSize	String	The size of the file. Unit: bytes.
Status	String	The status of the URL upload job. For more information, see Status: URL upload job status.
CreationTime	String	The time when the job was created.
CompleteTime	Long	The time when the job was completed.
UserData	String	The user-defined field.
ErrorCode	String	The error code.
ErrorMessage	String	The error message.

Status: URL upload job status

Value	Description
PENDING	The job is submitted and is waiting to be processed.
PROCESSING	The job is being processed.
DOWNLOADING	The file is being downloaded.
DOWNLOAD_SUCCESS	The file is downloaded.
DOWNLOAD_FAIL	The file failed to be downloaded.
UPLOADING	The file is being uploaded.
UPLOAD_SUCCESS	The upload is successful.
UPLOAD_FAIL	The upload failed.
SUCCESS	The job is successful and the callback is complete.

Audio and video playback

VideoBase: Basic video information

Name	Type	Description
VideoId	String	The video ID.
Title	String	The video title.
Duration	String	The video duration. Unit: seconds.
CoverURL	String	The video thumbnail.
Status	String	The video status.
CreationTime	String	The time when the video was created. The time is in UTC.
MediaType	MediaType	The type of the media file. Valid values: video: video audio: audio-only

Note

By default, playback operations return an accelerated CDN URL. If no domain name is configured, playback operations return the URL of the origin server in OSS. In this case, only URLs of MP4 files can be used for playback.

PlayInfo: Video playback information

Name	Type	Description
Bitrate	String	The bitrate of the video stream. Unit: Kbit/s.
Definition	String	The definition of the video stream. Valid values: FD: low definition LD: standard definition SD: high definition HD: ultra high definition OD: original quality 2K: 2K 4K: 4K
Specification	String	The output specifications for audio and video transcoding. For more information, see Output specifications.
Duration	String	The length of the video stream. Unit: seconds.
Encrypt	Long	Indicates whether the video stream is encrypted. Valid values: 0: No 1: Yes
EncryptType	String	The encryption type of the video stream. Valid values: AliyunVoDEncryption: Alibaba Cloud Video Encryption (private encryption) HLSEncryption: HLS encryption
PlayURL	String	The playback URL of the video stream.
Format	String	The format of the video stream. If the media file is a video, valid values are: mp4 m3u8 If the media file is audio-only, the valid value is mp3.
Fps	String	The frame rate of the video stream, in frames per second.
Size	Long	The size of the video stream. Unit: bytes.
Width	Long	The width of the video stream. Unit: pixel.
Height	Long	The height of the video stream. Unit: pixel.
StreamType	String	The type of the media stream. If the media stream is a video, the value is video. If the media stream is audio-only, the value is audio.
JobId	String	The ID of the transcoding job for the media stream. This ID serves as the unique identifier for the media stream.
WatermarkId	String	The ID of the watermark associated with the current media stream.
Status	String	The status of the video stream. Valid values: Normal: The latest transcoded stream for each definition and format is in the Normal status. Invisible: If multiple streams are transcoded for the same definition and format, the latest stream is marked as Normal, and the others are marked as Invisible.
NarrowBandType	String	The type of Narrowband HD. Valid values: 0: normal 1.0: Narrowband HD 1.0 2.0: Narrowband HD 2.0 This parameter takes effect only when a definition from the built-in Narrowband HD 1.0 transcoding template is configured. For more information, see TranscodeTemplate: Transcoding template configuration.
CreationTime	String	The time when the stream was created. The time is in UTC.
ModificationTime	String	The time when the stream was updated. The time is in UTC.

VideoMeta: Video metadata

Name	Type	Description
VideoId	String	The video ID.
Title	String	The video title.
Duration	Float	The video duration. Unit: seconds.
CoverURL	String	The video thumbnail.
Status	String	The video status.

Media asset search

Media: Media information

Name	Type	Description
MediaId	String	The ID of the media asset.
CreationTime	String	The time when the media asset was created. The time is in UTC.
MediaType	String	The type of the media file. Valid values: video: video audio: audio image: image attached: auxiliary media asset
Video	Video	The video information.
Audio	Audio	The audio information.
Image	Image	The image information.
AttachedMedia	AttachedMedia	The auxiliary media asset information.

Media asset categorization

Category: Media asset category

Name	Type	Description
CateId	Long	The ID of the video category.
CateName	String	The name of the category. The value can be up to 64 bytes in length and must be in UTF-8.
ParentId	Long	The ID of the parent category. The parent ID of a level 1 category is -1.
Level	Long	The level of the category. A level 1 category is at level 0.

Live to VOD

LiveRecordVideo: Live-to-VOD recording information

Name	Type	Description
StreamName	String	The name of the live stream.
DomainName	String	The domain name.
AppName	String	The name of the app.
PlaylistId	String	The ID of the playlist.
RecordStartTime	String	The start time of the recording.
RecordEndTime	String	The end time of the recording.
Video	Video	The video information.

Online editing: Video editing and production

EditingProject: Online editing project

Name	Type	Description
ProjectId	String	The ID of the online editing project.
Title	String	The title of the online editing project.
CreationTime	String	The time when the online editing project was created. The time is in UTC and follows the yyyy-MM-ddTHH:mm:ssZ format. For example, 2017-01-11T12:00:00Z corresponds to 20:00:00 on January 11, 2017 (UTC+8).
ModifiedTime	String	The time when the online editing project was last modified. The time is in UTC and follows the yyyy-MM-ddTHH:mm:ssZ format. For example, 2017-01-11T12:00:00Z corresponds to 20:00:00 on January 11, 2017 (UTC+8).
Status	String	The status of the online editing project.
Description	String	The description of the online editing project.
Timeline	String	The timeline of the online editing project. The value is a JSON string.
Duration	String	The total duration of the online editing project. This is the same as the total duration of the timeline.
CoverURL	String	The thumbnail URL of the online editing project.

ProjectStatus: Online editing project status

Value	Description	Notes
Normal	Draft	The initial status of the online editing project.
Producing	Producing	None.
Produced	Production successful	None.
ProduceFailed	Production failed	None.

Material: Material information for an online editing project

Note

This type refers to materials in a general sense, and includes materials in material management and videos in the media library.

Name	Type	Description
MaterialId	String	The material ID.
Title	String	The material title.
Description	String	The material description.
Duration	Float	The duration of the material. Unit: seconds. The value is accurate to four decimal places.
CoverURL	String	The thumbnail URL of the material.
Status	String	The material status.
CreationTime	String	The time when the material was created. The time is in UTC.
Size	Long	The size of the source file of the material. Unit: bytes.
CateId	Long	The category ID of the material.
CateName	String	The category name of the material.
Tags	String	The tags of the material. Separate multiple tags with commas (,).
Snapshots	String[]	An array of material snapshot URLs.
Sprites	String[]	An array of material sprite URLs.

ProduceConfig: Video production configuration

Name	Type	Description
TemplateGroupId	String	The ID of the transcoding template group to use for transcoding after video production is complete. The produced file is used as the source file. This process is similar to the transcoding process after an upload is complete. This parameter is optional. If left empty, the default template group in the transcoding settings is used. If specified, the designated template group is used. You can view the template group ID in the transcoding settings of the console.
TemplateId	String	The ID of the production template used for video production, which generates the source file for the media asset. This parameter is optional. If left empty, the built-in online editing template is used for production. If the production target is a video file, the built-in template uses the H.264 encoding format and the MP4 container format. If you have other requirements and want to specify production parameters (such as animated GIF production, intelligent subtitling, M3U8 fast clipping, or custom production parameters), you can submit a ticket to apply.
Width	Integer	The width of the output video frame. Unit: pixel. This parameter is optional. The default value depends on the resolution of the source files of the materials used in the timeline. The maximum width and height are used. For example, if three materials with source file resolutions of 1280 × 720, 1920 × 1080, and 720 × 1280 are used in the timeline, the resolution of the final produced video is 1920 × 1280.
Height	Integer	The height of the output video frame. Unit: pixel. This parameter is optional. The default value depends on the resolution of the source files of the materials used in the timeline. The maximum width and height are used. For example, if three materials with source file resolutions of 1280 × 720, 1920 × 1080, and 720 × 1280 are used in the timeline, the resolution of the final produced video is 1920 × 1280.
Bitrate	Integer	The bitrate of the output video. Unit: Kbit/s. This parameter is optional. The default value depends on the bitrate of the source files of the materials used in the timeline. The maximum bitrate is used. For example, if three materials with source file bitrates of 400 Kbit/s, 600 Kbit/s, and 800 Kbit/s are used in the timeline, the bitrate of the final produced video is 800 Kbit/s.
StorageLocation	String	The storage address of the file. This is required for all regions except China (Shanghai).

MediaMetadata: Metadata of the produced video

Name	Type	Description
Title	String	The title of the produced video. The title can be up to 128 bytes in length and must be in UTF-8.
Description	String	The description of the produced video. The description can be up to 1,024 bytes in length and must be in UTF-8.
CoverURL	String	The URL of the custom thumbnail for the produced video.
CateId	String	The category ID of the produced video. In the ApsaraVideo VOD console, choose Configuration Management > Media Asset Management Configuration > Category Management to edit or view the category ID.
Tags	String	The tags of the produced video. A single tag can be up to 32 bytes in length. You can add a maximum of 16 tags. Separate multiple tags with commas (,). The value must be in UTF-8.

Online editing - Timeline (for the new editor)

Note

The online editing feature is not supported in specific regions. Make sure that the feature is supported in the region where ApsaraVideo VOD is activated before you use the feature. For more information, see Regions. For more information about the online editing data types for the old editor, see Online editing data types - old editor.

Timeline: Timeline information

A timeline is the product of arranging materials and designing effects based on a video concept. A timeline mainly consists of tracks, materials, and effects.

Name	Type	Required	Description
VideoTracks	VideoTrack[]	No. The video track and audio track cannot both be empty.	A list of video tracks. The tracks are layered in the same order as the array elements. For example, the track corresponding to the first element is at the bottom layer, the track for the second element is layered on top of it, and so on.
AudioTracks	AudioTrack[]	No. The audio track and video track cannot both be empty.	A list of audio tracks.
SubtitleTracks	SubtitleTrack[]	No	A list of subtitle tracks.
EffectTracks	EffectTrack[]	No	A list of effect tracks.

VideoTrack: Video track information

A VideoTrack is used to arrange visual materials, such as videos and images.

Name	Type	Required	Description
Type	String	No	The default is a normal video track. When Type=Effect, the current track can be used as an effect track. You can fill VideoTrackClips with EffectTrackItem.
MainTrack	Boolean	No	Specifies whether the current track is the main track. The default value is False.
VideoTrackClips	VideoTrackClip[]	Yes	A list of material clips on the video track.

AudioTrack: Audio track information

An AudioTrack is used to arrange audio materials, including audio-only materials and video materials that contain an audio stream.

Name	Type	Required	Description
MainTrack	Boolean	No	Specifies whether the current track is the main track. The default value is False.
AudioTrackClips	AudioTrackClip[]	Yes	A list of material clips on the audio track.

SubtitleTrack: Subtitle track information

A SubtitleTrack is used to arrange subtitles, including banner text and external subtitles.

Name	Type	Required	Description
SubtitleTrackClips	SubtitleTrackClip[]	Yes	A list of material clips on the subtitle track.

EffectTrack: Effect track information

An EffectTrack is used to add effects to the entire video. Filters and VFX are supported.

Name	Type	Required	Description
EffectTrackItems	EffectTrackItem[]	Yes	A list of effect track clips.

VideoTrackClip: Video track material information

VideoTrackClip materials include video materials and image materials.

The In, Out, TimelineIn, and TimelineOut parameters specify the trim points of the material and its position on the timeline. For example, to place the segment from 5s to 10s of a video at the 15s to 20s mark on the timeline, set In=5, Out=10, TimelineIn=15, and TimelineOut=20.

Name	Type	Required	Description
MediaId	String	No	The media ID of the video track material clip. In some cases, the media ID is also called the audio/video ID (VideoId) or image ID (ImageId).
Type	String	No	The type of the material clip. The default value is Video. Valid values: Video Image GlobalImage (global image). The duration of a global image is calculated based on the duration of the longest video track by default. Example: Use a global image in a video track
X	Float	No	The horizontal distance from the upper-left corner of the image or video to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's width. An integer value of 2 or greater represents an absolute pixel value.
Y	Float	No	The vertical distance from the upper-left corner of the image or video to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's height. An integer value of 2 or greater represents an absolute pixel value.
Width	Float	No	The width of the image in the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's width. An integer value of 2 or greater represents an absolute pixel value.
Height	Float	No	The height of the image in the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's height. An integer value of 2 or greater represents an absolute pixel value.
AdaptMode	String	No	The adaptive scaling mode for the video size. The default value is Fill. This mode takes effect only when you set both the Width and Height of the video track. In this case, Width and Height define the target area, and the video scales adaptively within this area. Contain: The content is scaled to fit the target area while preserving its aspect ratio. Cover: The content fills the entire target area while preserving its aspect ratio. If the aspect ratio of the object does not match the content box, the object is cropped to fit the target area. Fill: The default logic. The content is stretched to fill the target content box. The entire object completely fills the box. If the aspect ratio of the object does not match the content box, the object is stretched to fit the target area.
In	Float	No	The in-point of the material clip relative to the material. This is used when the material is an audio or video file. Unit: seconds. The value is accurate to four decimal places. If you do not specify In, the default value is 0.
Out	Float	No	The out-point of the material clip relative to the material. This is used when the material is an audio or video file. Unit: seconds. The value is accurate to four decimal places. If you do not specify Out, the material duration is used as the default value.
MaxOut	Float	No	The maximum out-point of the material clip relative to the material. If you set this parameter, the out-point of the clip is set to the smaller value between the material duration and this parameter's value. This parameter is used for audio and video materials. Unit: seconds. The value is accurate to four decimal places. If you set the Out parameter, the MaxOut parameter becomes invalid. Example: Set the MaxOut out-point in a video track
Duration	Float	No	The duration of the material clip. This is generally used when the material is an image. Unit: seconds. The value is accurate to four decimal places.
DyncFrames	Int	No	The frame rate of the animated image. This is used when the material is an animated image. Example: Use GIF stickers
TimelineIn	Float	No	The in-point of the material clip relative to the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the value is automatically calculated based on the sequential order of the material clips.
TimelineOut	Float	No	The out-point of the material clip relative to the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the value is automatically calculated based on the sequential order of the material clips.
Speed	Float	No	The speed of the video material. The value ranges from 0.1 to 100. For example, if Speed=2, the video is processed at 2x speed, the duration of the clip is halved, and it is produced into the final video. Example: Change audio and video speed
MaskVideoUrl	String	No	The URL of the mask video. This is typically a video with an alpha channel used to add a transparency effect to the original video. Only public OSS URLs are supported.
Effects	Effect[]	No	A list of effects for the material clip.

AudioTrackClip: Audio track material information

AudioTrackClip materials include audio-only materials and video materials that have an audio stream.

Name	Type	Required	Description
MediaId	String	No	The media ID of the audio track material clip.
In	Float	No	The in-point of the material clip relative to the material. Unit: seconds. The value is accurate to four decimal places. If you do not specify In, the default value is 0.
Out	Float	No	The out-point of the material clip relative to the material. Unit: seconds. The value is accurate to four decimal places. If you do not specify Out, the material duration is used as the default value.
TimelineIn	Float	No	The in-point of the material clip relative to the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the value is automatically calculated based on the sequential order of the material clips.
TimelineOut	Float	No	The out-point of the material clip relative to the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the value is automatically calculated based on the sequential order of the material clips.
Speed	Float	No	The speed of the audio material. The value ranges from 0.1 to 100. For example, if Speed=2, the audio is processed at 2x speed, the duration of the clip is halved, and it is produced into the final video. Example: Change audio and video speed
Effects	Effect[]	No	A list of effects for the material clip.
LoopMode	Boolean	No	The loop playback effect for the material clip on the timeline. True: loop playback. False (default): normal playback without a loop. Example: Loop audio playback

SubtitleTrackClip: Subtitle track material information

SubtitleTrackClip represents subtitle materials.

Name	Type	Required	Description
Type	String	Yes	The type of the subtitle material. Valid values: Subtitle: external subtitle file Text: banner text
SubType	String	No	The subtype of the subtitle material. Valid values: srt: external SRT subtitle ass: external ASS subtitle You can ignore this parameter if the subtitle material type is banner text.
FileURL	String	No	The OSS address of the subtitle file. This parameter is required when the subtitle type is external subtitle. The format is: https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.srt Example: Use a subtitle file directly for editing Note FileURL supports only public OSS URLs. Accelerated OSS URLs, CDN URLs, or other HTTP URLs are not supported.
X	Float	No	When the subtitle type is banner text, this indicates the horizontal distance from the upper-left corner of the text to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's width. An integer value of 2 or greater represents an absolute pixel value.
Y	Float	No	When the subtitle type is banner text, this indicates the vertical distance from the upper-left corner of the text to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's height. An integer value of 2 or greater represents an absolute pixel value.
TimelineIn	Float	No	When the subtitle type is banner text, this indicates the start position of the text on the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the value is automatically calculated based on the sequential order of the materials.
TimelineOut	Float	No	When the subtitle type is banner text, this indicates the end position of the text on the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the value is automatically calculated based on the sequential order of the materials.
Content	String	No	When the subtitle type is banner text, this parameter is required. It indicates the text content.
Font	String	No	The font of the text. This parameter takes effect if you set Type to Text. Default value: SimSun. For more information about the supported fonts, see Fonts.
FontSize	Int	No	When the subtitle type is banner text, this indicates the font size.
FontColor	String	No	When the subtitle type is banner text, this indicates the color of the text, in the format of # followed by a hexadecimal value. For example: #ffffff.
FontColorOpacity	String	No	When the subtitle type is banner text, this indicates the transparency of the text. The value ranges from 0 to 1. The default is 1. 1 is opaque, and 0 is fully transparent.
FontFace	FontFace	No	When the subtitle type is banner text, this indicates the font appearance.
Spacing	Int	No	When the subtitle type is banner text, this indicates the character spacing of the banner text. Unit: pixel. The default is 0.
Angle	Float	No	When the subtitle type is banner text, this indicates the counter-clockwise rotation angle of the banner text. Unit: degree. The default is 0.
BorderStyle	Int	No	Sets the border and shadow format for the banner text. Valid values are 1 or 3. 1=border+shadow, 3=opaque background box. The default is 1.
Outline	Int	No	When the subtitle type is banner text, this indicates the outline width of the banner text. Unit: pixel. The default is 0.
OutlineColour	String	No	When the subtitle type is banner text, this indicates the outline color of the banner text, in the format of # followed by a hexadecimal value. For example: #ffffff.
Shadow	Int	No	When the subtitle type is banner text, this indicates the depth of the shadow cast by the banner text. Unit: pixel. The default is 0.
BackColour	String	No	When the subtitle type is banner text, this indicates the shadow color of the banner text, in the format of # followed by a hexadecimal value. For example: #ffffff.
Alignment	String	No	When the subtitle type is banner text, this sets the alignment. The default is TopLeft. Valid values: TopLeft: upper-left corner of the video TopCenter: top center of the video's vertical axis TopRight: upper-right corner of the video CenterLeft: left center of the video's horizontal axis CenterCenter: center of the video CenterRight: right center of the video's horizontal axis BottomLeft: lower-left corner of the video BottomCenter: bottom center of the video's vertical axis BottomRight: lower-right corner of the video
AdaptMode	String	No	Automatically wraps or scales the banner text when it exceeds the video width or the specified TextWidth. Valid values: AutoWrap: auto wrap AutoScale: auto scaling AutoWrapAtSpaces: Automatically wraps text only at spaces. This is suitable for auto-wrapping English-only subtitles.
TextWidth	Integer	No	The width of the subtitle text box. This takes effect when AdaptMode is set. The text box width is set to this value for auto wrapping or scaling. If not specified, the video width is used for auto wrapping or scaling. Unit: pixel.
FontUrl	String	No	When the subtitle type is banner text, you can use the path of a font file in your OSS bucket to generate subtitles. The TTF, OTF, and WOFF font file formats are supported. For example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/example-font.ttf
EffectColorStyle	String	No	When the subtitle type is banner text, this indicates the word art style type of the banner text. For more information about word art types and effects, see Word art effect examples.
AaiMotionInEffect	String	No	When the subtitle type is banner text, this indicates the entrance effect type of the banner text. For more information about caption entrance effects, see Entrance effects.
AaiMotionIn	Float	No	When the subtitle type is banner text, this indicates the duration of the entrance effect. Unit: seconds. The value is accurate to four decimal places. If AaiMotionIn is not specified, the default is 0.5s. If the text duration is less than 0.5s, the value is the total duration minus the exit duration.
AaiMotionOutEffect	String	No	Specifies the entrance effect type for banner text captions. For the available caption entrance effects, see Entrance effects.
AaiMotionOut	Float	No	When the subtitle type is banner text, this indicates the duration of the exit effect. Unit: seconds. The value is accurate to four decimal places. If AaiMotionOut is not specified, the default is 0.5s. If the text duration is less than 0.5s, the value is the total text duration.
AaiMotionLoopEffect	String	No	When the subtitle type is banner text, this indicates the loop effect type of the banner text. It cannot be effective at the same time as the entrance or exit effects. For more information about the loop effects, see Loop effects.
Ratio	Float	No	When the subtitle type is banner text, this indicates the playback speed of the loop effect. The value is accurate to four decimal places. If not specified, the default is 1. A value greater than 1 means a faster loop, and a value less than 1 means a slower loop.

EffectTrackItem: Effect track clip information

EffectTrackItem types include VFX and filters.

Name	Type	Required	Description
Type	String	Yes	The type of the effect track clip. Supported values: VFX, Filter.
SubType	String	Yes	The subtype of the effect track segment. For more information about the supported effects, see Effect examples and Filter effect examples.
TimelineIn	Float	No	The start position of the effect clip on the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the default is 0.
TimelineOut	Float	No	The end position of the effect clip on the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the default is the end time of the video.
Duration	Float	No	The duration of the effect clip on the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify Duration, the default is the video duration. Note Only one of Duration and TimelineOut can take effect.
X	Float	No	This parameter is supported only when SubType is set to mosaic_rect/blur. The horizontal distance from the upper-left corner of the effect area to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's width. An integer value of 2 or greater represents an absolute pixel value.
Y	Float	No	This parameter is supported only when SubType is set to mosaic_rect/blur. The vertical distance from the effect area to the upper-left corner of the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's height. An integer value of 2 or greater represents an absolute pixel value.
Width	Float	No	This parameter is supported only when SubType is set to mosaic_rect/blur. The width of the effect area in the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's width. An integer value of 2 or greater represents an absolute pixel value.
Height	Float	No	This parameter is supported only when SubType is set to mosaic_rect/blur. The height of the effect area in the output video. Note: Both percentage and pixel values are supported. A value from 0 to 0.9999 represents a percentage of the output video's height. An integer value of 2 or greater represents an absolute pixel value.

FontFace: Font style

Name	Type	Required	Description
Bold	Boolean	No	Bold.
Italic	Boolean	No	Italic.
Underline	Boolean	No	Underline.

Effect: Effect information

Different effect types have unique properties that can be set, in addition to a set of common properties.

For more information about effect parameters, see Effect configurations.

The common properties of Effect are as follows:

Name

Type

Required

Description

Type

String

Yes

The effect type. Valid values:

Text: banner text, video track material.
DeWatermark: masking, video track material.
Crop: crop, video track material.
Scale: scaling, video track material.
Pad: padding, video track material.
Background: background settings, video track material.
Transition: transition, video track material.
VFX: effect, video track material.
Filter: filter, video track material.
Volume: volume adjustment, audio track material.
AFade: audio fade in and fade out, audio track material.
Rotate: material rotation, video track material.
Clip: random trim.
Flip: flip.
KenBurns: Ken Burns effect.
Zoom: zoom.

SubType

String

The effect subtype.

If you set Type to Transition, this parameter indicates the subtype of the transition effect. For more information about this parameter, see Transition effect examples.
If you set Type to VFX, this parameter indicates the subtype of the visual effect. For a list of supported values, see Visual effect examples.
If you set Type to Filter, this parameter indicates the subtype of the filter effect. For more information about this parameter, see Filter effect examples.

Video snapshots/Animated stickers

SnapshotJob: Snapshot job information

Name	Type	Description
JobId	String	The job ID.

VodTemplateInfo: Snapshot template information

Name	Type	Description
Name	String	The template name.
VodTemplateId	String	The template ID.
TemplateType	String	The template type. Valid values: Snapshot: An image captured from a screen. DynamicImage: animated sticker
IsDefault	String	Indicates whether it is the default template. Valid values: Default: default watermark NotDefault: not the default watermark
TemplateConfig	JSON	The detailed template configuration, which is a JSON string. Valid values: For Snapshot configurations, see SnapshotTemplateConfig. For DynamicImage configurations, see DynamicImageTemplateConfig.
CreationTime	String	The creation time, in UTC.
ModifyTime	String	The modification time, in UTC.

MediaSnapshot: Media snapshot data

Name	Type	Description
JobId	String	The ID of the snapshot job.
CreationTime	String	The time when the snapshot job was created. The time is in UTC.
Total	Long	The total number of snapshots.
Regular	String	The rule for generating snapshot URLs.
Snapshots	Snapshot[]	The snapshot data.

Snapshot: Snapshot information

Name	Type	Description
Index	String	The index value of the snapshot.
Url	String	The snapshot URL.

DynamicImage: Animated sticker information

Name	Type	Description
VideoId	String	The ID of the audio or video file.
DynamicImageId	String	The ID of the animated sticker.
FileURL	String	The URL of the animated sticker file.
Width	String	The width of the animated sticker.
Height	String	High-quality animation.
Duration	String	The duration of the animated sticker.
Format	String	The format of the animated image. Valid values: gif and webp.
FileSize	String	The size of the animated sticker file.
Fps	String	The frame rate of the animated sticker.

Video watermarks

WatermarkInfo: Watermark information

Name	Type	Required	Description
CreationTime	String	Yes	The time when the watermark was created.
Name	String	Yes	The name of the watermark.
IsDefault	String	Yes	Specifies if the watermark is the default. Valid values: Default: The watermark used by default. NotDefault: Specifies a non-default watermark.
Type	String	Yes	The type of the watermark. Valid values: Image Text: "Text."
WatermarkId	String	Yes	The ID of the watermark.
FileUrl	String	No	The URL of the watermark file. The URL can be an OSS or CDN URL. This parameter is not returned for text watermarks.
WatermarkConfig	WatermarkConfig	Yes	The configuration for a text or image watermark, such as its position and effects. The value is a JSON string.

Audio and video transcoding

TranscodeJob: the information about a transcoding job

Name	Type	Description
JobId	String	The ID of the transcoding job.

TranscodeTemplateGroup: Transcoding template group

Name	Type	Required	Description
Name	String	Yes	The name of the transcoding template group.
TranscodeTemplateGroupId	String	Yes	The ID of the transcoding template group.
IsDefault	String	Yes	Specifies whether this is the default template group. Valid values: Default: The template group is the default. NotDefault: The template group is not the default.
CreationTime	String	Yes	The time when the transcoding template group was created.
ModifyTime	String	Yes	The time when the transcoding template group was last modified.
TranscodeTemplateList	TranscodeTemplate[]	Yes	A list of transcoding template configurations.

TranscodeTemplate: Transcoding template configuration

Name	Type	Required	Description
Type	String	No	The template type. Valid values: Normal: A normal transcoding template. You cannot set the PackageSetting parameter for this template type. VideoPackage: A video stream packaging template. This template type first transcodes the video and then creates an adaptive bitrate stream. You must configure the PackageSetting parameter. SubtitlePackage: A caption packaging template. This template type does not transcode the video. It only packages the specified caption information into the adaptive bitrate output file. You must set the PackageSetting parameter. This template type cannot be used alone in a template group. It must be configured with a template of the VideoPackage type & a template group can contain only one template of this type. Default value: Normal.
Video	Video	Yes	The transcoding parameters for the video stream. The value is a JSON string.
Audio	Audio	Yes	The transcoding parameters for the audio stream. The value is a JSON string.
Definition	String	Yes	The definition marker for a normal transcoding template. Valid values: LD: Low definition. SD: Standard definition. HD: High definition. FHD: Ultra high definition. OD: Original quality. This value is used for container format conversion. 2K 4K SQ: Standard quality audio. HQ: High quality audio. Note This definition is a data marker for the transcoding template. It does not represent the actual output specifications, such as the resolution range, of the video. For more information about the mapping between definitions and output specifications, see Specification. This definition marker does not affect transcoding billing. For more information about transcoding billing specifications, such as the resolution range, see ApsaraVideo VOD transcoding duration packages. The definition marker for a built-in Narrowband HD 1.0 transcoding template. Valid values: LD-NBV1: Low definition. SD-NBV1: Standard definition. HD-NBV1: High definition. FHD-NBV1: Ultra high definition. 2K-NBV1 4K-NBV Note You cannot modify the definition marker for any transcoding template. The audio resolution, video resolution, bitrate, and other parameters of Narrowband HD 1.0 transcoding templates are built-in and cannot be modified. For more information about the parameters, see Narrowband HD transcoding. You can create Narrowband HD 1.0 transcoding templates only for the FLV, M3U8 (HLS), and MP4 output formats.
Container	Container	Yes	The container format for encapsulating audio and video streams. The value is a JSON string.
MuxConfig	MuxConfig	No	The sharding configuration for transcoding. This parameter is required for HLS transcoding. The value is a JSON string.
TransConfig	TransConfig	No	The conditional transcoding parameters. Set this parameter to perform logical checks based on the bitrate and resolution of the source file before generating the output video. The value is a JSON string.
TranscodeFileRegular	String	No	The custom output path for transcoded files. Note The following wildcard characters are supported: {MediaId} (video ID), {JobId} (transcoding job ID), and {PlayDefinition} (the definition marker returned by the GetPlayInfo operation). The value can contain only digits, letters, braces ({}), forward slashes (/), hyphens (-), and underscores (_). The value can be up to 128 characters in length. The custom output path must start with {MediaId}. Configuration example {MediaId}/watermark-{PlayDefinition}. During transcoding, {MediaId} is replaced with the video ID, such as 8ff5cc93f6da4079a47a77bf71d, and {PlayDefinition} is replaced with the definition marker, such as fd. Output example 8ff5cc93f6da4079a47a77bf71d/watermark-fd.mp4. The file extension, such as .mp4, .m3u8, or .flv, is automatically added.
Clip	Clip	No	The video cropping configuration. The value is a JSON string. For example, set this parameter to extract a 5-second clip from a video to generate a new video.
Rotate	String	No	The rotation angle of the video, in degrees. Valid values: [0, 360]. For example, a value of 180 turns the video upside down.
EncryptSetting	EncryptSetting	No	The encryption configuration for transcoding.
PackageSetting	PackageSetting	No	The packaging configuration. Only HLS adaptive bitrate stream packaging and DASH packaging are supported. The value is a JSON string.
SubtitleList	SubtitleConfig	No	The caption configuration. The value is a JSON string.
WatermarkIds	String[]	No	The IDs of the watermarks to associate with the output video. You can associate a maximum of four watermarks. The keyword `USER_DEFAULT_WATERMARK` represents the ID of the default watermark.
TranscodeTemplateId	String	No	The ID of the transcoding template. This parameter is required when you modify a template.
TemplateName	String	No	The name of the transcoding template. This parameter is required when you add a template.

Example of the TranscodeTemplate parameter

{
        "Type":"VideoPackage",
        "Video":{
                "Codec":"H.264",
                "Bitrate":"900",
                "Width":"960",
                "Remove":"false",
                "Fps":"30"
        },
        "Audio":{
                "Codec":"AAC",
                "Bitrate":"128",
                "Samplerate":"44100"
        },
        "Container":{
                "Format":"m3u8"
        },
        "MuxConfig":{
                "Segment":{
                        "Duration":"6"
                }
        },
        "EncryptSetting":{
                "EncryptType":"AliyunVoDEncryption"
        },
        "PackageSetting":{
                "PackageType":"HLSPackage"
                "PackageConfig":{
                        "BandWidth":"900000"
                }
        },
       "SubtitleUrl": "http://outin-40564284ef058b2163e1****.oss-cn-shanghai.aliyuncs.com/subtitles/c737f-14f1-4364-b107-d5f7f8ed****-cn.ass",
        "CharEncode": "UTF-8",
        "WatermarkIds":["USER_DEFAULT_WATERMARK","ddddddddd"],
        "Definition":"SD",
        "TemplateName":"test"
}

Video: Transcoding video stream configuration

Note

In most cases, you can simply set the Codec, Bitrate, Height, and Width parameters, and set the Remove parameter to false.
To maintain the aspect ratio of the source video, set only the Width or Height parameter for the output video.

Name	Type	Required	Description
Codec	String	Yes	The video encoding format. Valid values: H.264 and H.265.
Remove	String	Yes	Specifies whether to remove the video stream from the output file. Valid values: true: The video stream is removed. false: The video stream is retained. Default: false.
Bitrate	String	No	The target bitrate of the output video, in Kbps. If not specified, the bitrate is determined by the Crf value. Value range: 10 to 50,000.
Height	String	No	The height of the output video in pixels. The value must be a multiple of 2 within the range of 128 to 4096. If this parameter is not specified, the height of the source file is used.
Width	String	No	The width of the output video in pixels. The value must be a multiple of 2 within the range of [128, 4096]. If unspecified, the width of the source video is used.
Fps	String	No	If you do not specify this parameter, the frame rate of the source file is used. The value must be greater than 0 and no more than 60 FPS.
Gop	String	No	The interval between adjacent keyframes in frames. The valid range is 1 to 100,000.
LongShortMode	String	No	Enables automatic rotation for landscape and portrait videos (the long/short edge pattern). The width of the transcoded output matches the long edge of the input video (the height of a portrait video), and the height matches the short edge (the width of a portrait video). Values: true: Enabled. false: Disabled. Default: true. This setting is recommended for portrait videos.
Crf	String	No	This parameter specifies the bitrate-quality control factor and overrides the `Bitrate` parameter. A higher value results in lower video quality and a smaller file size. Conversely, a lower value results in higher video quality and a larger file size, but increases the transcoding time. The value can range from 0 to 51. Default: 26. Modifying this value is not recommended.
Profile	String	No	The encoding profile. The valid values are: baseline: Suitable for mobile devices. main: Suitable for standard-definition devices. high: Suitable for high-definition devices. Default: high. Best practices If you are creating multiple outputs with different definitions, set the profile for the lowest definition to baseline. This ensures compatibility with older devices. Use main or high for the other definitions.
Preset	String	No	Valid values: veryfast, fast, medium, slow, slower. Default: medium. Modifying this value is not recommended.
ScanMode	String	No	The scan mode. Valid values: interlaced: Interlaced scan. progressive: Progressive scan.
Bufsize	String	No	The buffer size in KB. The value must be from 1000 to 128000. Default: 6,000.
Maxrate	String	No	The peak video bitrate in kbps. The value must be an integer from 1000 to 50000.
PixFmt	String	No	The pixel format. Standard pixel formats such as yuv420p and yuvj420p are supported. Default value: yuv420p or the color format of the input video.

Example of the Video parameter

{
        "Codec":"H.264",
        "Bitrate":"128",
        "Remove":"false",
        "Width":"640",
        "Fps":"30"
}

Audio: Transcoding configurations for an audio stream

Note

In most cases, you can simply set the Codec and Bitrate parameters, and set the Remove parameter to false.

Name	Type	Required	Description
Codec	String	Yes	The audio coding format. Valid values: AAC and MP3.
Bitrate	String	Yes	The bitrate of the audio output. Unit: Kbps. The value must be an integer from 8 to 1000.
Remove	String	Yes	Specifies whether to remove the audio stream. true: Removes the audio stream from the transcoded output file. false: Keeps the audio stream in the transcoded output file. Default value: false.
Samplerate	String	Yes	The sample rate. Unit: Hz. Valid values: 22050, 32000, 44100, 48000, and 96000. Default value: 44100. If the video container format is FLV and the audio coding format is MP3, the sample rates 32000, 48000, and 96000 are not supported. If the audio coding format is MP3, the sample rate 96000 is not supported.
Channels	String	No	The number of sound channels. Default value: 2. If Codec is set to MP3, the number of channels can be only 1 or 2. If Codec is set to AAC, the number of channels can be 1, 2, 4, 5, 6, or 8.
Profile	String	No	The audio coding profile. If Codec is set to AAC, valid values are aac_low, aac_he, aac_he_v2, aac_ld, and aac_eld.
Volume	Volume	No	The volume parameters.

Example of the Audio parameter

{
        "Codec":"AAC",
        "Bitrate":"128",
        "Remove":"false",
        "Samplerate":"44100"
}

Container: the container format

Name

Type

Required

Description

Format

String

Yes

The container format.

Video transcoding supports FLV, MP4, and HLS (M3U8 and TS).
Audio transcoding supports MP3 and MP4.
If the container format is FLV, the video codec cannot be set to H.265.

Container parameter example

{
        "Format":"mp4"
}

MuxConfig: the segment configuration for HLS

Note

You must specify this parameter if the container format is set to M3U8.

Name	Type	Required	Description
Segment	Segment	Yes	The segment configuration. The value must be a JSON object.

Segment: Detailed segment configuration

Name

Type

Required

Description

Duration

String

Yes

The duration of the TS segment. The value must be an integer. Valid values: [1,60]. Unit: seconds.

Example: {"Duration":"10"}.

Example of the MuxConfig parameter

{
        "Segment":{
                "Duration":"10"
        }
}

TransConfig: conditional transcoding configuration

Name	Type	Required	Description
TransMode	String	No	The transcoding mode. Valid values: onepass: The average bitrate (ABR) mode. This mode provides a faster encoding speed than the twopass mode. This is the default codec for Alibaba Cloud. twopass: The variable bitrate (VBR) mode. The encoder runs twice to accurately assign the bitrate. This produces a smaller file with higher quality. The twopass mode takes more time than the onepass mode. Therefore, it is not suitable for time-sensitive scenarios such as live streaming and real-time communication. Do not use the twopass mode if the input video is already highly compressed. This can cause blocking artifacts. CBR: The constant bitrate (CBR) mode. The file has a constant bitrate from beginning to end. Compared with VBR and ABR, this mode produces larger files without a significant improvement in video quality. Default: onepass.
IsCheckReso	String	No	Specifies whether to check the source resolution to determine if the transcoding should use the original resolution. Valid values: true: Checks the resolution. If the output resolution is higher than the source resolution, based on width or height, the output resolution is set to the source resolution. false: Does not check the resolution. Default: false.
IsCheckResoFail	String	No	Specifies whether to check the source resolution to determine if the transcoding task should fail. Valid values: true: Checks the resolution. If the output resolution is higher than the source resolution, based on width or height, the transcoding task fails. false: Does not check the resolution. Default: false.
IsCheckVideoBitrate	String	No	Specifies whether to check the source video stream bitrate to determine if the transcoding should use the original video bitrate. Valid values: true: Checks the video bitrate. If the output video bitrate is higher than the source video bitrate, the output video bitrate is set to the source video bitrate. false: Does not perform a check. Default: false.
IsCheckVideoBitrateFail	String	No	Specifies whether to check the source video stream bitrate to determine if the transcoding task should fail. Valid values: true: Checks the video bitrate. If the output video bitrate is higher than the source video bitrate, the transcoding task fails. false: No check is performed. Default: false. This parameter has a higher priority than IsCheckVideoBitrate.
IsCheckAudioBitrate	String	No	Specifies whether to check the source audio stream bitrate to determine if the transcoding should use the original audio bitrate. Valid values: true: Checks the audio bitrate. If the output audio bitrate is higher than the source audio bitrate, the output audio bitrate is set to the source audio bitrate. false: No check is performed. Default: false.
IsCheckAudioBitrateFail	String	No	Specifies whether to check the source audio stream bitrate to determine if the transcoding task should fail. Valid values: true: Checks the audio bitrate. If the output audio bitrate is higher than the source audio bitrate, the transcoding task fails. false: Does not perform a check. Default: false. This parameter has a higher priority than IsCheckAudioBitrate.

Example of the TransConfig parameter

{
        "IsCheckReso":"true",
        "IsCheckResoFail":"false",
        "IsCheckVideoBitrate":"false",
        "IsCheckVideoBitrateFail":"false",
        "IsCheckAudioBitrate":"false",
        "IsCheckAudioBitrateFail":"false"
}

Clip: Video Clipping Settings

Name	Type	Required	Description
TimeSpan	TimeSpan	Yes	The time parameters used to crop a video.

TimeSpan: Video Crop Settings

Name	Type	Required	Description
Seek	String	Yes	The start time for the video crop. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 12000.55. Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:05.003. Use Format 1.
Duration	String	No	The duration of the video crop. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 12000.55. Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:05.003. Use Format 1. Note Set either the Duration or End parameter. If you set both, End takes precedence.
End	String	No	The duration to trim from the end of the video. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 12000.55. Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:05.003. Use Format 1. Note Set either the Duration or End parameter. If you set both, End takes precedence. The duration between the start time and the end time cannot exceed the total duration of the video.

EncryptSetting: the encryption configuration for transcoding

Note

To use HLS encryption, set the EncryptType parameter to AliyunVoDEncryption in the transcoding template. Then, configure the EncryptConfig parameter when you call the SubmitTranscodeJobs operation.

Name

Type

Required

Description

EncryptType

String

Yes

The encryption type. Valid values:

AliyunVoDEncryption: The private encryption or HLS encryption for videos in M3U8 format.
AliyunVoDLicenseEncryption: The private encryption for videos in MP4 format.

Example of the EncryptSetting parameter

{
        "EncryptType":"AliyunVoDEncryption"
}

PackageSetting: Transcoding and packaging settings

Note

Packaging audio and video streams after extraction is not supported.
Only HLS adaptive bitrate packaging is supported.

Name	Type	Required	Description
PackageType	String	Yes	The packaging type. Set the value to HLSPackage for HLS adaptive bitrate packaging.
PackageConfig	PackageConfig	No	The packaging configuration. This parameter is required for VideoPackage templates.
SubtitleExtractConfigList	SubtitleExtractConfig[]	No	The caption packaging configuration. This parameter is required for SubtitlePackage templates. Do not specify this parameter for other template types.

PackageConfig: video packaging configuration

Note

This parameter is required only for packaging HLS adaptive streams.

Name

Type

Required

Description

BandWidth

String

Yes

The maximum bandwidth. This parameter is required for HLS packaging. Unit: bit/s.

Configure this parameter only for VideoPackage.

Example of the PackageSetting parameter

Sample code for configuring a video stream packaging template:
{
        "PackageType":"HLSPackage",
        "PackageConfig":{
                "BandWidth":"400000"
        }
}

SubtitleExtractConfig: Caption packaging configuration

Name	Type	Required	Description
SubtitleUrlList	String[]	Yes	The URL of the subtitle file. Only HTTP OSS URLs are supported. HTTP CDN URLs and HTTPS URLs are not supported. Note Only one HTTP URL is supported. Store subtitle files only in the system buckets allocated by video-on-demand.
Language	String	Yes	The subtitle language, such as en-US. For more information, see RFC 5646.
Format	String	Yes	The format of the subtitle file. Only the VTT format is supported. For example, subtitle.vtt.
Name	String	Yes	The display name of the subtitle track in the player, such as Chinese or English.

Example of the SubtitlePackage parameter

Sample code for configuring a subtitle packaging template:
 {
      "PackageType": "HLSPackage",
      "SubtitleExtractConfigList": [
        {
          "SubtitleUrlList": [
            "http://outin-40514****.oss-cn-shanghai.aliyuncs.com/subtitles/4bff3675-79a5-40fa-8c86-1f98169d****-eng.vtt"
          ],
          "Language": "en-US",
          "Format": "vtt",
          "Name": "English"
        },
        {
          "SubtitleUrlList": [
            "http://outin-40514****.oss-cn-shanghai.aliyuncs.com/subtitles/a3f50b08-11c3-4511-94cf-7fd4f7a5****-jpn.vtt"
          ],
          "Language": "ja",
          "Format": "vtt",
          "Name": "Japanese"
        },
        {
          "SubtitleUrlList": [
            "http://outin-40514****.oss-cn-shanghai.aliyuncs.com/subtitles/4dba87c2-a787-42cd-8328-2369aeb8****-cn.vtt"
          ],
          "Language": "cn",
          "Format": "vtt",
          "Name": "Chinese"
        }
      ]
    }

SubtitleConfig: Subtitle configuration

Name

Type

Required

Description

SubtitleUrl

String

Yes

The OSS URL of the subtitle file. HTTPS URLs and CDN accelerated domain names are not supported. Supported subtitle formats: srt and ass.

Note

The subtitle file and the video source file must be stored in the same bucket in the same region, such as the China (Shanghai) region.

CharEncode

String

Yes

The encoding format. Valid values:

auto: The system automatically detects the encoding format.
UTF-8
GBK
BIG5

Default value: UTF-8.

Note

For more information about how to upload a subtitle file, see CreateUploadAttachedMedia and Upload files to OSS.

Example of the SubtitleConfig parameter

{
        "SubtitleUrl": "http://outin-40564284ef058b2d300163e1****.oss-cn-shanghai.aliyuncs.com/subtitles/c737f-14f1-4364-b107-d5f7f8ed****.ass",
        "CharEncode": "UTF-8"
}

Volume configuration

Name	Type	Required	Description
Method	String	No	The volume adjustment method. Valid values: auto, dynamic, and linear.
IntegratedLoudnessTarget	String	No	The target volume. The value must be a number from -70 to -5. This parameter is required only when Method is set to dynamic. Default value: -6.
TruePeak	String	No	The peak volume. The value must be a number from -9 to 0. This parameter is required only when Method is set to dynamic. Default value: -1.
LoudnessRangeTarget	String	No	The volume range. The value must be a number from 1 to 20. This parameter is required only when Method is set to dynamic. Default value: 8.

Example of the Volume parameter

{
        "Method":"dynamic",
        "IntegratedLoudnessTarget":"-6",
        "TruePeak":"-1",
        "LoudnessRangeTarget":"8"
}

Supported combinations of container formats and audio encoding formats

Container	Audio Codecs
mp3	MP3
mp4	AAC
ogg	VORBIS and FLAC
flac	FLAC

Supported combinations of container formats, audio encoding formats, and video encoding formats

Container	Video Codecs	Audio Codecs
flv	H.264	AAC and MP3
mp4	H.264 and H.265	AAC and MP3
ts	H.264 and H.265	AAC and MP3
m3u8	H.264 and H.265	AAC and MP3
gif	GIF	Not supported

Supported combinations of video encoding formats and video stream parameters

Video Codecs	H.264	H.265	GIF
Profile	√	×	×
Bitrate	√	√	×
Crf	✓	Supported	×
Width	✓	√	√
Height	√	√	Yes
Fps	√	✓	✓
Gop	Supported	√	×
Preset	√	×	×
ScanMode	✓	√	√
Bufsize	√	√	×
Maxrate	✓	Supported	×
PixFmt	√	√	bgr8

TranscodeSummary: Transcoding summary

Name	Type	Description
VideoId	String	The ID of the audio or video file.
TranscodeTemplateGroupId	String	The ID of the transcoding template group.
TranscodeStatus	String	The status of the transcoding task. Valid values: Processing: The transcoding task is in progress. Partial: Some transcoding jobs are complete. CompleteAllSucc: All transcoding jobs completed successfully. CompleteAllFail: All transcoding jobs failed. If the source file is invalid, no transcoding jobs are initiated, and the entire transcoding task fails. CompletePartialSucc: All transcoding jobs are complete, but only some are successful.
TranscodeJobInfoSummaryList	TranscodeJobInfoSummary[]	The summaries of transcoding jobs.
CreationTime	String	The creation time of the transcoding job. The time is in UTC. The format is yyyy-MM-ddTHH:mm:ssZ.
CompleteTime	String	The time when the transcoding job was completed. The time is in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format.

TranscodeJobInfoSummary: the summary of a transcoding job

Name	Type	Description
TranscodeTemplateId	String	The ID of the transcoding template.
Width	String	The width of the output video. Unit: px.
Height	String	The height of the output video. Unit: px.
Duration	String	The duration of the output video. Unit: seconds.
Filesize	String	The size of the output video file. Unit: bytes.
Bitrate	String	The average bitrate of the output video. Unit: kbps.
Fps	String	The frame rate of the output video. Unit: frames per second.
Format	String	The container format of the output video.
WatermarkIdList	String[]	The list of watermark IDs used for transcoding.
TranscodeProgress	Long	The transcoding progress. The value ranges from 0 to 100.
TranscodeJobStatus	String	The status of the transcoding job. Valid values: Transcoding: The job is in progress. TranscodeSuccess: The job is successful. TranscodeFail: The job failed.
CreationTime	String	The time when the transcoding job was created. The time is in UTC and uses the yyyy-MM-ddTHH:mm:ssZ format.
CompleteTime	String	The time when the transcoding job was completed. The time is in UTC and uses the yyyy-MM-ddTHH:mm:ssZ format.
ErrorCode	String	The error code returned if the transcoding job fails.
ErrorMessage	String	The error message returned if the transcoding job fails.

TranscodeTask: Transcoding job information

Name	Type	Description
TranscodeTaskId	String	The ID of the transcoding task.
TranscodeTemplateGroupId	String	The ID of the transcoding template group.
VideoId	String	The ID of the video.
TaskStatus	String	The status of the transcoding task. Valid values: Processing: The transcoding is in progress. Partial: Some transcoding jobs are complete. CompleteAllSucc: All transcoding jobs are complete and successful. CompleteAllFail: All transcoding jobs failed. If the source file is invalid, no transcoding jobs are initiated, and the entire transcoding task fails. CompletePartialSucc: All transcoding jobs are complete, but only some were successful.
CreationTime	String	The time when the transcoding task was created. The time is in UTC and follows the yyyy-MM-ddTHH:mm:ssZ format.
CompleteTime	String	The time when the transcoding task was completed. The time is in UTC and follows the yyyy-MM-ddTHH:mm:ssZ format.
Trigger	String	The trigger type. Valid values: Auto: Transcoding is automatically triggered after a video is uploaded. Manual: Transcoding is triggered by calling the SubmitTranscodeJobs operation.
TranscodeJobInfoList	TranscodeJobInfo	The information about transcoding jobs.

TranscodeJobInfo: Transcoding job information

Name	Type	Description
TranscodeTaskId	String	The ID of the transcoding task.
TranscodeJobId	String	The ID of the transcoding job.
VideoId	String	The ID of the video.
TranscodeProgress	Long	The progress of the transcoding job. Valid values: [0, 100].
TranscodeJobStatus	String	The status of the transcoding job. Valid values: Transcoding: The transcoding job is in progress. TranscodeSuccess: The transcoding job is successful. TranscodeFail: The transcoding job failed.
Priority	String	The priority of the transcoding task.
Definition	String	The definition. Note The definition mark that is configured in the transcoding template. This value does not represent the actual resolution of the output file.
TranscodeTemplateId	String	The ID of the transcoding template.
CreationTime	String	The time when the transcoding job was created.
CompleteTime	String	The time when the transcoding job was completed.
InputFileUrl	String	The OSS URL of the source file.
OutputFile	OutputFile	Information about the output file.
ErrorCode	String	The error code returned if the transcoding job fails.
ErrorMessage	String	The error message returned if the transcoding job fails.

OutputFile: Transcoding output file

Name	Type	Description
OutputFileUrl	String	The OSS URL of the output file.
Format	String	The container format of the output file.
Width	String	The image width of the output file. Unit: pixels.
Height	String	The image height of the output file. Unit: pixels.
Duration	String	The duration of the output file. Unit: seconds.
Bitrate	String	The average bitrate of the output file. Unit: kbps.
Fps	String	The frame rate of the output file. Unit: frames per second.
Filesize	Long	The size of the output file. Unit: bytes.
EncryptType	String	The encryption type of the output file. The value is a JSON string.
WatermarkIdList	String	The list of watermark IDs applied to the output file.
VideoStreamList	String	The list of video streams. For more information, see VideoStream: Video stream information.
AudioStreamList	String	The list of audio streams. For more information, see AudioStream: Audio stream information.

Data Statistics

TopPlayVideoStatis: the daily playback statistics on one of the top videos

Name	Type	Description
VideoId	String	The ID of the audio or video file.
PlayDuration	String	The playback duration of the video. Unit: milliseconds.
Title	String	The title of the video.
VV	String	The number of video views.
UV	String	The number of unique visitors.

VideoPlayStatisDetail: The daily playback statistics of a specific video

Name	Type	Description
Date	String	The date in the yyyyMMdd format. Example: 20170120.
PlayDuration	String	The playback duration of the video. Unit: milliseconds.
Title	String	The title of the video.
VV	String	The number of video views.
UV	String	The number of unique visitors.
PlayRange	String	The distribution of the playback duration.

UserPlayStatisTotals: the statistics on total playbacks per day

Name	Type	Description
Date	String	The date in the yyyyMMdd format. Example: 20170120.
PlayDuration	String	The total playback duration. Unit: milliseconds.
PlayRange	String	The playback duration distribution.
VV	VV	The total number of video views.
UV	UV	The total number of unique visitors.

UserPlayStatisAvgs: The statistics on average daily playbacks per user

Name	Type	Description
Date	String	The date in the yyyyMMdd format. Example: 20170120.
AvgPlayDuration	String	The average playback duration of the video. Unit: milliseconds.
AvgPlayCount	String	The average number of video views.

Playback Count VV Distribution

Only statistics on video playbacks that use ApsaraVideo Player SDKs are supported.

Name	Type	Description
Android	String	The total number of playbacks on the Android player.
iOS	String	The total number of playbacks from the iOS player.
Flash	String	The total number of playbacks from the Flash player.
HTML5	String	The total number of playbacks from the HTML5 player.

UV distribution by playback count

Only statistics on video playbacks that use ApsaraVideo Player SDKs are supported.

Name	Type	Description
Android	String	The total number of unique visitors who use ApsaraVideo Player SDK for Android.
iOS	String	The total number of unique users for playback using ApsaraVideo Player SDK for iOS.
Flash	String	Total number of users for Flash Player playback.
HTML5	String	The total number of unique visitors who use ApsaraVideo Player SDK for HTML5.

Notifications

MessageCallback: Event notification configuration

Name	Type	Description
CallbackType	String	The callback method. Valid values: HTTP and MNS.
CallbackURL	String	The webhook address for HTTP callbacks.
MnsEndpoint	String	The public Internet endpoint for MNS callbacks.
MnsQueueName	String	The name of the MNS queue for MNS callbacks.
EventTypeList	String	The type of the callback event.
AuthSwitch	String	The authentication switch for HTTP callbacks. Valid values: on: Enabled. off: Disabled.
AuthKey	String	The authentication key for HTTP callbacks.

Multi-application system

AppInfo: Application information

Name	Type	Description
AppId	String	The ID of the application.
AppName	String	The name of the application.
Description	String	The description of the application.
Type	String	The application type. Valid values: System: A default application. Custom: A user-created application.
Status	String	The application status. Valid values: Normal: Indicates a normal state. Disable: The application is inactive.
CreationTime	String	The time when the application was created, in UTC.
ModificationTime	String	The update time is in UTC.

AppPolicy: Application authorization policy information

Name	Type	Description
AppId	String	The ID of the application.
PolicyType	String	The policy type. Valid values: System: A system policy. Custom: A user-defined policy.
PolicyName	String	The name of the policy.
CreationTime	String	The UTC time when the resource was created.
Description	String	The description of the policy.