Basic data types of the ApsaraVideo VOD API - ApsaraVideo VOD

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

Basic Media Asset Information

Video: audio and video information

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

Status: Audio and video status

Value	Description	Remarks
Uploading	Uploading	This is the initial status of an audio or video file. It indicates that the audio or video file is being uploaded. If your audio or video files are in this status for a long period of time, view the possible causes and solutions described in FAQ about media asset upload. Only delete operations are allowed for audio or video files in this status. You cannot perform other operations, such as transcoding, video clip, or media asset review, on audio or video files that are being uploaded.
UploadFail	Upload failed	Uploads may fail due to network issues or source file corruption. Retry the upload or use a different source file. When using resumable upload, this status does not appear because it is impossible to determine if the upload failed. Only delete operations are allowed for audio or video files in this status. You cannot perform other operations, such as transcoding, video clip, or media asset review, on audio or video files that failed to upload.
UploadSucc	Upload complete	If the default transcoding process is skipped during upload due to business design or other reasons, preventing the generation of valid playback streams, or if a non-transcoding template group is used and the source file is not in MP4, FLV, M3U8, MP3, or WEBM format, the video is marked as Upload complete. After subsequent transcoding generates valid playback streams, the video changes to the Normal status. You can perform operations such as transcoding, video clip, and media asset review on audio or video files in this status.
Transcoding	Transcoding	Media files in this status are being transcoded. If a video is undergoing initial transcoding, no valid playback streams are available, and you cannot call API operations to obtain playback URLs. You can determine the transcoding status using the Single Definition Transcoding Complete or Transcode complete event notifications.
TranscodeFail	Transcoding failed	Transcoding failures are usually caused by errors in the source file. You can obtain the error message from the Single Definition Transcoding Complete or Transcode complete event notification. For more information about how to troubleshoot transcoding failures, see FAQ about transcoding.
Checking	Reviewing	If you enable Review Before Publish in the ApsaraVideo VOD console > Review Management > Review Settings, audio or video files automatically enter the review flow after successful transcoding. The audio or video file status is then marked as Reviewing. You must initiate a manual review; otherwise, the audio or video file remains in the Reviewing status. You can play audio and video files in this status only using the ApsaraVideo VOD console or review security IP addresses. You cannot call API operations or use SDKs to obtain the playback URLs of audio or video files in this status for playback. However, you can still play these files using valid playback URLs that are publicly accessible. You can perform operations such as transcoding and video clip on audio or video files in this status. Note Note that the Reviewing status here describes the audio or video file's status (viewable in the Status column under ApsaraVideo VOD console > Media Assets > Audio/Video). This differs from the Reviewing status for machine-assisted moderation (viewable in the ApsaraVideo VOD console > Review Management > Video Review). The machine-assisted moderation Reviewing status only describes the machine review job status, while the audio or video file's Reviewing status describes both machine-assisted and manual review job statuses.
Blocked	Blocked	Audio or video in this state can be played only in the ApsaraVideo VOD console or from whitelisted IP addresses for review. You cannot use an API or SDK to obtain the playback URL for the audio or video. However, valid playback URLs that have already been exposed can still be played normally. Only delete operations are allowed for audio or video files in this status. You cannot perform other operations, such as transcoding, video clip, or media asset review, on blocked audio or video files.
Normal	Normal	If at least one valid playback stream exists for the audio or video file, it is in the Normal status. You can perform all operations, such as transcoding, video clip, media asset review, and playback, on audio or video files in this status.
ProduceFail	Synthesis failed	This indicates that video clip production failed. When using ApsaraVideo VOD's online editing for video clip production, ensure that all media assets used 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 Object Storage Service (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 ID of the category.
CateName	String	The name of the category.
Description	String	Description.
StorageLocation	String	Storage address.
Mezzanine	Mezzanine	The source information about 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: the status of an image.
AppId	String	The ID of the application.

Status: the status of an image

Value	Description	Remarks
Uploading	Uploading	This is the image's initial status, indicating it is being uploaded. If your images remain in this status for a long period, see Why Are My Uploaded Files Always in the Uploading Status?.
UploadFail	The image failed to be uploaded.	Uploads may fail due to network issues or source file corruption. Retry or upload a different source file.
Normal	Normal	Image upload successful.

AttachedMediaInfo: the information about an auxiliary media asset

Name	Type	Description
MediaId	String	The ID of the auxiliary media asset.
URL	String	The URL of the auxiliary media asset. If a domain name for CDN is specified, a CDN URL is returned. Otherwise, an OSS URL is returned.
Title	String	Title.
Tags	String	Tag.
Type	String	The type of the auxiliary media asset.
Categories	Category[]	The categories.
Description	String	Description
StorageLocation	String	Storage address.
CreationTime	String	The time when the auxiliary media asset was created. The time must be in UTC.
ModificationTime	String	The time when the auxiliary media asset was last modified. The time must be in UTC.
Status	String	The status of the auxiliary media asset. For more information, see Status: Auxiliary Media Asset Status.
AppId	String	The ID of the application.

Status: the status of an auxiliary media asset

Value	Description	Explanation
Uploading	Uploading	The initial status. The auxiliary media asset is being uploaded.
Normal	Normal	The auxiliary media asset was uploaded successfully.
UploadFail	Failed	The auxiliary media asset failed to upload.

Media Resource File Information

Mezzanine: Audio and video source file information

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

VideoStream: Video stream information

Name	Type	Description
Index	String	The ordinal number of the video stream. This identifies the position of the video stream in the 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 text of the encoding format.
CodecTag	String	The tag of the encoding format.
Width	Long	The width of the video resolution.
Height	Long	Video resolution is high.
HasBFrames	String	Indicates whether the stream has B-frames.
Sar	String	Resolution ratio of the encoded signal.
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. The value must be in the range of [0, 360).

AudioStream: Audio stream information

Name	Type	Description
Index	String	The ordinal number of the audio stream. This identifies the position of the audio stream in the 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 text 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: Status of an audio or video source file

Value	Description	Remarks
Uploading	Uploading	The initial state of the file. This indicates that the file is being uploaded.
Normal	Normal	The file was uploaded successfully.
UploadFail	Failed	The file failed to upload.
Deleted	Deleted	The file was 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 file size in bytes.
Width	Integer	The width of the image in pixels (px).
Height	Integer	The height of the image in pixels (px).

Upload multiple media files in a batch based on URLs

URLUploadInfo: the information about a URL-based upload job

Name	Type	Description
JobId	String	The ID of the upload job.
UploadURL	String	The URL of the file to be uploaded.
MediaId	String	The ID of the file to be uploaded.
FileSize	String	The size of the file to be uploaded. Unit: bytes.
Status	String	The status of the URL-based upload job. For more information about this parameter, see Status: the status of a URL-based upload job.
CreationTime	String	The time when the job was created.
CompleteTime	Long	The time when the job was complete.
UserData	String	A user-defined field.
ErrorCode	String	Error code
ErrorMessage	String	Error message.

Status: the status of a URL-based upload job

Value	Description
PENDING	The upload job is submitted and is waiting to be processed.
PROCESSING	You can start processing the task.
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 file is uploaded.
UPLOAD_FAIL	The file failed to be uploaded.
SUCCESS	The upload job is successful, and the callback is complete.

Video and audio playback

VideoBase: Basic video information

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

Note

By default, the playback API operation returns a CDN-accelerated URL. If a domain name is not configured, the API operation returns an OSS origin URL. In this case, only URLs of MP4 files can be used for playback.

PlayInfo: Playback information for a media stream

Name	Type	Description
Bitrate	String	The bitrate of the media stream, in Kbps.
Definition	String	The definition of the media stream. Valid values: FD: low definition LD: standard definition SD: high definition High Definition (HD). OD: original quality 2K: 2K 4K: 4K
Specification	String	The output specifications for video and audio transcoding. For more information, see Output specifications.
Duration	String	The duration of the media stream, in seconds.
Encrypt	Long	Indicates whether the media stream is encrypted. Valid values: 0: No. 1: Yes.
EncryptType	String	The encryption type of the media stream. Valid values: AliyunVoDEncryption: Alibaba Cloud Video Encryption (private encryption). HLSEncryption: HLS encryption.
PlayURL	String	The playback URL of the media stream.
Format	String	The format of the media 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 media stream, in frames per second (fps).
Size	Long	The size of the media stream, in bytes.
Width	Long	The width of the media stream, in pixels (px).
Height	Long	The height of the media stream, in pixels (px).
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 is the unique identifier of the media stream.
WatermarkId	String	The ID of the watermark that is associated with the media stream.
Status	String	The status of the media stream. Valid values: Normal: The status of the latest completed transcoding stream for each definition and format. Invisible: The status for redundant streams. When 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: regular 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 configurations.
CreationTime	String	The time when the stream was created. The time is in UTC.
ModificationTime	String	The time when the stream was last updated. The time is in UTC.

VideoMeta: Video metadata

Name	Type	Description
VideoId	String	The ID of the video.
Title	String	The title of the video.
Duration	Float	The duration of the video, in seconds.
CoverURL	String	Video thumbnail.
Status	String	The status of the video.

Query media assets

Media: the information about a media asset

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

Media asset categories

Category: media asset classification

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

Live to VOD

LiveRecordVideo: Information about the live-to-VOD recording

Name	Type	Description
StreamName	String	The name of the live stream.
DomainName	String	The domain name.
AppName	String	The name of the application.
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

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 follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC. For example, a value of 2017-01-11T12:00:00Z indicates 20:00:00 on January 11, 2017, in Beijing time (UTC+8).
ModifiedTime	String	The last modified time of the online editing project. The time is in UTC, using the yyyy-MM-ddTHH:mm:ssZ format. For example, 2017-01-11T12:00:00Z (which is 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. It must be 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	Remarks
Normal	Draft	This is the initial status of an online editing project.
Producing	Rendering	None.
Produced	Video production is successful.	None.
ProduceFailed	Synthesis failed.	None.

Material: material information for an online editing project

Note

This type refers broadly to materials, including both materials from the Material Management module and videos from the Media Library.

Name	Type	Description
MaterialId	String	The ID of the material.
Title	String	The title of the material.
Description	String	Material description.
Duration	Float	The duration of the material in seconds. The value is accurate to four decimal places.
CoverURL	String	The thumbnail URL of the material.
Status	String	Material status.
CreationTime	String	The time when the material was created. The time is displayed in UTC.
Size	Long	The size of the source file in bytes.
CateId	Long	The material category ID.
CateName	String	The material category name.
Tags	String	Tags for the material. Separate multiple tags with a comma (,).
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 used to transcode the produced video files. The produced videos serve as the source files for transcoding. This process is similar to the transcoding that runs after a file upload completes. This field is optional. If empty, the default template group from transcoding settings is used. If specified, the given template group is used. To view the template group ID, go to Transcoding Settings in the ApsaraVideo VOD console.
TemplateId	String	The composition template ID used for video composition to generate source files for media resources. This field is optional. If the value is empty, the built-in online editing template is used for composition. If the composition target is a video file, the built-in template's encoding format is H.264, and the container format is MP4. If you have other requirements to specify composition parameters (such as animated image composition, intelligent subtitling, M3U8 quick editing, or custom composition parameter support), submit a ticket to apply.
Width	Integer	The width of the output video, in pixels. This parameter is optional. By default, the output video resolution is set using the maximum width and maximum height from all source files in the timeline. For example, if a timeline contains three source files with resolutions of 1280 × 720 pixels, 1920 × 1080 pixels, and 720 × 1280 pixels, the output video resolution is 1920 × 1280 pixels.
Height	Integer	The height of the output video in pixels. This parameter is optional. By default, the output resolution is set using the maximum width and maximum height from all source files in the timeline. For example, if a timeline uses three source files with resolutions of 1280×720, 1920×1080, and 720×1280, the output video resolution is 1920×1280.
Bitrate	Integer	The bitrate of the produced video. Unit: Kbit/s. This parameter is optional. The default value is the maximum bitrate of the source files that you specified in Timeline. For example, you specify three materials for Timeline and the bitrates of the source files are 400, 600, and 800 Kbit/s. In this case, the default bitrate of the produced video is 800 Kbit/s.
StorageLocation	String	The storage address of the file. This parameter is required for regions other than China (Shanghai).

MediaMetadata: metadata of the produced video

Name	Type	Description
Title	String	The title of the produced video. The value can be up to 128 bytes in length and must be encoded in UTF-8.
Description	String	The description of the produced video. The value can be up to 1,024 bytes in length and must be encoded in UTF-8.
CoverURL	String	The URL of the custom thumbnail for the produced video.
CateId	String	The category ID of the produced video. Log on to the ApsaraVideo VOD console. In the navigation pane on the left, choose Configuration Management > Media Management > Categories.
Tags	String	The tags of the produced video. Each tag name can be up to 32 bytes in length. You can specify a maximum of 16 tags. Separate multiple tags with commas (,). The string must be encoded in the UTF-8 format.

Online editing - Timeline (for the new editor)

Note

Online editing capabilities vary by region. Before you use this feature, confirm that your service region supports it. For more information, see Service regions. For parameter descriptions related to online editing data types in the legacy editor, see Online editing data types (for the legacy editor).

Timeline: timeline information

A timeline is the result of arranging media assets and applying effects based on your creative vision for the video. It primarily contains three types of objects: tracks, media assets, and effects.

Name	Type	Required	Description
VideoTracks	VideoTrack[]	No. If VideoTracks is empty, AudioTracks must not be empty.	List of video tracks. The stacking order of multiple tracks follows the array element order. For example, the layer of the first array element appears at the bottom, the second element's layer appears above it, and so on.
AudioTracks	AudioTrack[]	No. If AudioTracks is empty, VideoTracks must not be empty.	List of audio tracks.
SubtitleTracks	SubtitleTrack[]	No	List of subtitle tracks.
EffectTracks	EffectTrack[]	No	List of effect tracks.

VideoTrack: video track information

VideoTrack arranges image-based media assets, including video and image materials.

Name	Type	Required	Description
Type	String	No	Defaults to a standard video track. When Type=Effect, the current track functions as an effect track. In this case, VideoTrackClips can contain EffectTrackItem.
MainTrack	Boolean	No	Specifies whether the current track is the main track. Default is False.
VideoTrackClips	VideoTrackClip[]	Yes	List of video track media clips.

AudioTrack: audio track information

AudioTrack arranges audio-based media assets, including audio-only files and videos with audio streams.

Name	Type	Required	Description
MainTrack	Boolean	No	Specifies whether the current track is the main track. Default is False.
AudioTrackClips	AudioTrackClip[]	Yes	List of audio track media clips.

SubtitleTrack: subtitle track information

SubtitleTrack arranges subtitles, including banner text and external subtitle files.

Name	Type	Required	Description
SubtitleTrackClips	SubtitleTrackClip[]	Yes	List of subtitle track media clips.

EffectTrack: effect track information

EffectTrack adds global effects to the entire video and supports filters and VFX.

Name	Type	Required	Description
EffectTrackItems	EffectTrackItem[]	Yes	List of effect track items.

VideoTrackClip: video track media information

VideoTrackClip includes both video and image media assets.

In, Out, TimelineIn, and TimelineOut mark the source clip’s start and end points and its placement on the timeline. For example, to place the 5- to 10-second segment of a video at the 15- to 20-second position on the timeline, you can set In=5, Out=10, TimelineIn=15, and TimelineOut=20.

Name	Type	Required	Description
MediaId	String	No	Media ID of the video track clip. In some contexts, this is also called VideoId (for video/audio) or ImageId (for images).
Type	String	No	Media clip type. Default is Video. Valid values: Video Image GlobalImage (global image; duration defaults to the longest video track duration.) Example: Use GlobalImage in a video track
X	Float	No	Horizontal distance from the top-left corner of the image or video to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video width. An integer ≥2 represents absolute pixels.
Y	Float	No	Vertical distance from the top-left corner of the image or video to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video height. An integer ≥2 represents absolute pixels.
Width	Float	No	Width of the image in the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video width. An integer ≥2 represents absolute pixels.
Height	Float	No	Height of the image in the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video height. An integer ≥2 represents absolute pixels.
AdaptMode	String	No	Video scaling mode. Default is Fill. This mode only takes effect when both Width and Height are set for the video track. In this case, Width and Height define the target area dimensions, and the video scales adaptively within that area. Contain: Scales the content to fit the target area while preserving its aspect ratio. Cover: Fills the entire target area while preserving aspect ratio. Content may be cropped if the aspect ratios do not match. Fill: Stretches the content to exactly fill the target area. Aspect ratio is not preserved.
In	Float	No	Start time of the clip relative to the source media. Applies only to audio/video sources. Unit: seconds, accurate to four decimal places. Defaults to 0 if not specified.
Out	Float	No	End time of the clip relative to the source media. Applies only to audio/video sources. Unit: seconds, accurate to four decimal places. Defaults to the full source duration if not specified.
MaxOut	Float	No	Maximum end time of the clip relative to the source media. If set, the actual Out point becomes the smaller of the source duration or MaxOut. Applies only to audio/video sources. Unit: seconds, accurate to four decimal places. If Out is specified, MaxOut is ignored. Example: Set MaxOut in a video track
Duration	Float	No	Duration of the clip. Typically used for image sources. Unit: seconds, accurate to four decimal places.
DyncFrames	Int	No	Frame rate for animated images. Applies only when the source is an animated image. Example: Use GIF stickers
TimelineIn	Float	No	Start time of the clip on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineIn is calculated automatically based on sequential placement.
TimelineOut	Float	No	End time of the clip on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineOut is calculated automatically based on sequential placement.
Speed	Float	No	Playback speed of the video clip. Valid range: 0.1–100. For example, Speed=2 plays the clip at double speed, halving its Duration in the final output. Example: Adjust audio/video speed
MaskVideoUrl	String	No	URL of the mask video. Typically a video with an alpha channel, used to add transparency effects to the original video. Only public OSS URLs are supported.
Effects	Effect[]	No	List of effects applied to the clip.

AudioTrackClip: audio track media information

AudioTrackClip includes audio-only files and videos that contain audio streams.

Name	Type	Required	Description
MediaId	String	No	Media ID of the audio track clip.
In	Float	No	Start time of the clip relative to the source media. Unit: seconds, accurate to four decimal places. Defaults to 0 if not specified.
Out	Float	No	End time of the clip relative to the source media. Unit: seconds, accurate to four decimal places. Defaults to the full source duration if not specified.
TimelineIn	Float	No	Start time of the clip on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineIn is calculated automatically based on sequential placement.
TimelineOut	Float	No	End time of the clip on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineOut is calculated automatically based on sequential placement.
Speed	Float	No	Playback speed of the audio clip. Valid range: 0.1–100. For example, Speed=2 plays the clip at double speed, halving its Duration in the final output. Example: Adjust audio/video speed
Effects	Effect[]	No	List of effects applied to the clip.
LoopMode	Boolean	No	Loop playback behavior for the clip on the timeline. True enables loop playback. False (default) disables looping. Example: Audio loop playback

SubtitleTrackClip: subtitle track media information

SubtitleTrackClip includes subtitle media assets.

Name	Type	Required	Description
Type	String	Yes	Subtitle media type. Valid values: Subtitle: external subtitle file Text: banner text
SubType	String	No	Subtitle media subtype. Valid values: srt: external SRT subtitle ass: external ASS subtitle Ignore this field when Type is Text.
FileURL	String	No	OSS URL of the subtitle file. Required when Type is Subtitle. Format: https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.srt Example: Edit directly using a subtitle file Note FileURL supports only public OSS URLs. Accelerated OSS URLs, CDN URLs, and other HTTP URLs are not supported.
X	Float	No	When Type is Text, horizontal distance from the top-left corner of the text to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video width. An integer >=2 represents absolute pixels.
Y	Float	No	When Type is Text, vertical distance from the top-left corner of the text to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video height. An integer >=2 represents absolute pixels.
TimelineIn	Float	No	When Type is Text, start time of the text on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineIn is calculated automatically based on sequential placement.
TimelineOut	Float	No	When Type is Text, end time of the text on the timeline. Unit: seconds, accurate to four decimal places. If not specified, TimelineOut is calculated automatically based on sequential placement.
Content	String	No	When Type is Text, required. Specifies the text content.
Font	String	No	When Type is Text, specifies the font. Default is SimSun. For the full list of supported fonts, see Font list.
FontSize	Int	No	When the caption type is banner text, it specifies the font size.
FontColor	String	No	When Type is Text, specifies the font color in hexadecimal format (# followed by hex digits). Example: #ffffff.
FontColorOpacity	String	No	When Type is Text, specifies font transparency. Valid range: 0–1. Default is 1 (opaque). 0 means fully transparent.
FontFace	FontFace	No	When Type is Text, specifies the font style.
Spacing	Int	No	When Type is Text, specifies character spacing. Unit: pixels. Default is 0.
Angle	Float	No	When Type is Text, specifies counterclockwise rotation angle. Unit: degrees. Default is 0.
BorderStyle	Int	No	Specifies border and shadow style for banner text. Valid values: 1 or 3. 1 = border + shadow. 3 = opaque background box. Default is 1.
Outline	Int	No	When Type is Text, specifies stroke width. Unit: pixels. Default is 0.
OutlineColour	String	No	When Type is Text, specifies stroke color in hexadecimal format (# followed by hex digits). Example: #ffffff.
Shadow	Int	No	When Type is Text, specifies shadow depth. Unit: pixels. Default is 0.
BackColour	String	No	When Type is Text, specifies shadow color in hexadecimal format (# followed by hex digits). Example: #ffffff.
Alignment	String	No	When Type is Text, specifies text alignment. Default is TopLeft. Valid values: TopLeft: top-left corner of the video TopCenter: top center along the vertical axis TopRight: top-right corner of the video CenterLeft: the left side of the video’s horizontal center axis CenterCenter: center of the video CenterRight: right center along the horizontal axis BottomLeft: bottom-left corner of the video BottomCenter: bottom center along the vertical axis BottomRight: bottom-right corner of the video
AdaptMode	String	No	Specifies how banner text adapts when it exceeds the video width or the specified TextWidth. Valid values: AutoWrap: automatically wraps lines AutoScale: Auto Scaling AutoWrapAtSpaces: wraps only at space characters (ideal for English-only subtitles)
TextWidth	Integer	No	Width of the subtitle text box. Takes effect only when AdaptMode is set. Automatic line wrapping or scaling uses this width. If not specified, the video width is used. Unit: pixels.
FontUrl	String	No	When Type is Text, supports custom font files from your OSS bucket. Supported formats: ttf, otf, woff. Example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/example-font.ttf
EffectColorStyle	String	No	When Type is Text, specifies the word art style. For word art styles and effects, see Word art effect examples.
AaiMotionInEffect	String	No	When Type is Text, specifies the entrance animation effect. For entrance effect types and examples, see Entrance effects.
AaiMotionIn	Float	No	When Type is Text, specifies the duration of the entrance effect. Unit: seconds, accurate to four decimal places. Defaults to 0.5 seconds if not specified. If the total text duration is less than 0.5 seconds, the entrance duration equals the total duration minus the exit duration.
AaiMotionOutEffect	String	No	When the subtitle type is banner, it specifies the entrance effect for banner text. For the types and effects of caption entrances, see Entrance effects.
AaiMotionOut	Float	No	When Type is Text, specifies the duration of the exit effect. Unit: seconds, accurate to four decimal places. Defaults to 0.5 seconds if not specified. If the total text duration is less than 0.5 seconds, the exit duration equals the total text duration.
AaiMotionLoopEffect	String	No	When Type is Text, specifies the loop animation effect. Cannot be used together with entrance or exit effects. For loop effect types and examples, see Loop effects.
Ratio	Float	No	When Type is Text, specifies the playback speed of the loop effect. Accurate to four decimal places. Defaults to 1 if not specified. Values greater than 1 speed up the loop. Values less than 1 slow it down.

EffectTrackItem: effect track item information

EffectTrackItem includes VFX and filter effects.

Name	Type	Required	Description
Type	String	Yes	Effect track item type. Valid values: VFX, Filter.
SubType	String	Yes	Effect track item subtype. For supported effect types and examples, see Special effect examples and Filter effect examples.
TimelineIn	Float	No	Start time of the effect on the timeline. Unit: seconds, accurate to four decimal places. Defaults to 0 if not specified.
TimelineOut	Float	No	End time of the effect on the timeline. Unit: seconds, accurate to four decimal places. Defaults to the video end time if not specified.
Duration	Float	No	Duration of the effect on the timeline. Unit: seconds, accurate to four decimal places. Defaults to the video duration if not specified. Note Only one of Duration or TimelineOut takes effect.
X	Float	No	Applies only when SubType is mosaic_rect or blur. Horizontal distance from the top-left corner of the effect area to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video width. An integer ≥2 represents absolute pixels.
Y	Float	No	Applies only when SubType is mosaic_rect or blur. Vertical distance from the top-left corner of the effect area to the top-left corner of the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video height. An integer ≥2 represents absolute pixels.
Width	Float	No	Applies only when SubType is mosaic_rect or blur. Width of the effect area in the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video width. An integer ≥2 represents absolute pixels.
Height	Float	No	Applies only when SubType is mosaic_rect or blur. Height of the effect area in the output video. Supports percentage or pixel values. A value between [0–0.9999] represents a percentage of the output video height. An integer ≥2 represents absolute pixels.

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, but they also share common attributes.

For detailed descriptions of individual Effect properties, see Effect configuration reference.

The common Effect properties are as follows:

Name

Type

Required

Description

Type

String

Yes

Effect type. Valid values:

Text: banner text for video track clips.
DeWatermark: watermark removal for video track clips.
Crop: cropping for video track clips.
Scale: scaling for video track clips.
Pad: Snapping video track clips
Background: background settings for video track clips.
Transition: transition effects for video track clips.
VFX: visual effects for video track clips.
Filter: filters for video track clips.
Volume: volume adjustment for audio track clips.
AFade: audio fade-in and fade-out for audio track clips.
Rotate: rotation for video track clips.
Clip: random clipping.
Flip: flipping.
KenBurns: Ken Burns effect (pan and zoom).
Zoom: zooming.

SubType

String

Effect subtype.

When Type is Transition, this specifies the transition subtype. For valid values, see Transition effect examples.
When Type is VFX, this specifies the visual effect subtype. For valid values, see Special effect examples.
When Type is Filter, this specifies the filter subtype. For valid values, see Filter effect examples.

Video snapshots and dynamic images

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: a snapshot. DynamicImage: a dynamic image.
IsDefault	String	Indicates whether this is the default watermark. Valid values: Default: The watermark is the default one. NotDefault: The watermark is not the default one.
TemplateConfig	JSON	The template's detailed configuration. The value is a JSON string. For more information about snapshot configuration, see SnapshotTemplateConfig. For the DynamicImage configuration, see DynamicImageTemplateConfig.
CreationTime	String	The time when the template was created. The time is in UTC format.
ModifyTime	String	The time when the template was last modified. The time is in UTC format.

MediaSnapshot: Media snapshot data

Name	Type	Description
JobId	String	The snapshot job ID.
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: Dynamic image information

Name	Type	Description
VideoId	String	The video ID.
DynamicImageId	String	The dynamic image ID.
FileURL	String	The URL of the dynamic image file.
Width	String	The width of the dynamic image.
Height	String	The height of the dynamic image.
Duration	String	The duration of the dynamic image.
Format	String	The format of the dynamic image. Valid values are `gif` or `webp`.
FileSize	String	The size of the dynamic image file.
Fps	String	The frame rate of the dynamic image.

Watermarks

WatermarkInfo: the information about a watermark

Name	Type	Required	Description
CreationTime	String	Yes	The time when the watermark was added.
Name	String	Yes	The name of the watermark.
IsDefault	String	Yes	Indicates whether the watermark is the default one. Valid values: Default: default watermark. NotDefault: A non-default watermark.
Type	String	Yes	The type of the watermark. Valid values: Image: A picture. Text: text.
WatermarkId	String	Yes	The ID of the watermark.
FileUrl	String	No	The OSS URL or CDN URL of the watermark file. This parameter does not apply to text watermarks.
WatermarkConfig	WatermarkConfig	Yes	The configurations for the position and effect of the text or image watermark. The value must be a JSON string.

Audio and video transcoding

TranscodeJob: information about a transcoding job

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

TranscodeTemplateGroup: information about a transcoding template group

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

TranscodeTemplate: transcoding template configuration

Name	Type	Required	Description
Type	String	No	The template type. Valid values: Normal: a regular transcoding template. You cannot set the PackageSetting parameter for this template type. VideoPackage: a video stream packaging template. This template first transcodes the video, then builds an adaptive bitrate stream. You must configure the PackageSetting parameter. SubtitlePackage: a subtitle packaging template. This template type does not perform transcoding. Instead, it embeds the corresponding caption information into adaptive bitrate output files. You must configure the PackageSetting parameter. However, this template type cannot exist independently in a template group. You must configure it together with a VideoPackage template, and you can configure only one such template in a template group. Default value: Normal.
Video	Video	Yes	The transcoding configuration for the video stream. The value must be a JSON string.
Audio	Audio	Yes	The transcoding configuration for the audio stream. The value must be a JSON string.
Definition	String	Yes	The definition of a regular 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 sound quality. HQ: high sound quality. Note This definition is only a tag in the transcoding template. It does not represent the actual resolution range of the output video. For more information about how template definitions map to output video resolutions, see Specification. This definition has no effect on transcoding fees. For more information about transcoding fees, see Transcoding plans of ApsaraVideo VOD. The definition of a 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 of any transcoding template. Narrowband HD™ 1.0 transcoding templates use system-defined parameters such as video resolution, audio resolution, and bitrate. You cannot modify these parameters. For more information, see Narrowband HD™ 1.0. You can create Narrowband HD 1.0 transcoding templates only for FLV, M3U8 (HLS), and MP4 output formats.
Container	Container	Yes	The container format used to encapsulate audio and video streams. The value must be a JSON string.
MuxConfig	MuxConfig	No	The segment configuration for transcoding. You must specify this parameter if the container format is HLS. The value must be a JSON string.
TransConfig	TransConfig	No	The conditional transcoding configuration. Use this parameter to apply basic logic based on the source video's bitrate and resolution before generating the transcoded video. The value must be a JSON string.
TranscodeFileRegular	String	No	The custom path for storing output files. Note Supported wildcards: {MediaId} (video ID), {JobId} (transcoding job ID), and {PlayDefinition} (definition returned by the GetPlayInfo operation). Only digits, English letters, braces {}, forward slashes (/), hyphens (-), and underscores (_) are allowed. The maximum length is 128 characters. The path must start with {MediaId}. Configuration example {MediaId}/watermark-{PlayDefinition}: During transcoding, ApsaraVideo VOD replaces {MediaId} with the video ID (for example, 8ff5cc93f6da4079a47a77bf71d) and {PlayDefinition} with the definition (for example, fd). Output example 8ff5cc93f6da4079a47a77bf71d/watermark-fd.mp4 (ApsaraVideo VOD automatically appends the file extension, such as .mp4, .m3u8, or .flv).
Clip	Clip	No	The video cropping configuration. The value must be a JSON string. For example, set this parameter to extract 5 seconds of content from a video to generate a new video.
Rotate	String	No	The rotation angle of the video. Valid values: [0,360]. For example, setting this parameter to 180 flips the video image upside down.
EncryptSetting	EncryptSetting	No	The encryption configuration for transcoding.
PackageSetting	PackageSetting	No	The packaging configuration. Only HLS adaptive bitrate packaging and DASH packaging are supported. The value must be a JSON string.
SubtitleList	SubtitleConfig	No	The subtitle configuration. The value must be a JSON string.
WatermarkIds	String[]	No	The IDs of associated watermarks. You can associate up to four watermark IDs. USER_DEFAULT_WATERMARK represents the ID of the default watermark.
TranscodeTemplateId	String	No	The ID of the transcoding template. You must specify this parameter when modifying a template.
TemplateName	String	No	The name of the transcoding template. You must specify this parameter when creating 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: video stream transcoding configuration

Note

If you have no special requirements, you can set only Codec, Bitrate, Height, Width, and Remove=false.
We recommend that you set only one of Width or Height for the output video. This ensures that the aspect ratio matches the source video.

Name	Type	Required	Description
Codec	String	Yes	The video encoding format: H.264 or H.265.
Remove	String	Yes	Indicates whether to remove the video stream. Valid values: true: removes the video stream from the output file. false: retains the video stream in the output file. Default value: false.
Bitrate	String	No	The target bitrate for the output video. If you do not specify this parameter, the bitrate is calculated using the Crf parameter. Unit: Kbps. Valid values: [10,50000].
Height	String	No	The height of the output video. The value must be a multiple of 2. If you do not specify this parameter, the height of the source file is used. Unit: pixels. Valid values: [128,4096].
Width	String	No	The width of the output video. The value must be a multiple of 2. If you do not specify this parameter, the width of the source file is used. Unit: pixels. Valid values: [128,4096].
Fps	String	No	The frame rate of the output video. If you do not specify this parameter, the frame rate of the source file is used. Unit: FPS. Valid values: (0,60].
Gop	String	No	The distance between adjacent keyframes. Unit: frames. Valid values: [1,100000].
LongShortMode	String	No	Enables auto-rotate screen. The output video width corresponds to the long side of the source (height in portrait mode). The output video height corresponds to the short side of the source (width in portrait mode). Valid values: true: Enabled. false: The feature is disabled. Default value: true. This feature works best for portrait videos. We recommend enabling it.
Crf	String	No	The bitrate quality control factor. If you specify this parameter, the Bitrate parameter is ignored. A higher value results in lower video quality and smaller file size. A lower value results in higher video quality, larger file size, and longer transcoding time. Valid values: [0,51]. Default value: 26. We do not recommend changing this value.
Profile	String	No	The encoding profile. Valid values: baseline: suitable for mobile devices. main: suitable for standard-definition devices. high: suitable for high-definition devices. Default value: high. This parameter applies only to H.264 encoding. Best practices If you support multiple definitions, set the lowest definition to baseline to ensure playback on low-end devices. Set other definitions to main or high.
Preset	String	No	The preset video algorithm. Valid values: veryfast, fast, medium, slow, slower. Default value: medium. This parameter applies only to H.264 encoding. We do not recommend changing this value.
ScanMode	String	No	The scan mode. Valid values: interlaced: interlaced scan. progressive: progressive scan.
Bufsize	String	No	The buffer size. Unit: KB. Valid values: [1000,128000]. Default value: 6000.
Maxrate	String	No	The peak video bitrate. Unit: Kbps. Valid values: [1000,50000].
PixFmt	String	No	The pixel format of the video. Standard formats such as yuv420p and yuvj420p are supported. Default value: yuv420p or the original pixel format.

Example of the Video parameter

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

Audio: audio stream transcoding configuration

Note

If you have no special requirements, you can set only Codec, Bitrate, and Remove=false.

Name	Type	Required	Description
Codec	String	Yes	The audio encoding format: AAC or MP3.
Bitrate	String	Yes	The target bitrate for the output audio. Unit: Kbps. Valid values: [8,1000].
Remove	String	Yes	Indicates whether to remove the audio stream. Valid values: true: removes the audio stream from the output file. false: retains the audio stream in the output file. Default value: false.
Samplerate	String	Yes	The sample rate. Unit: Hz. Valid values: 22050, 32000, 44100, 48000, 96000. Default value: 44100. If the container format is FLV and the audio codec is MP3, the sample rate cannot be 32000, 48000, or 96000. If the audio codec is MP3, the sample rate cannot be 96000.
Channels	String	No	The number of audio channels. Default value: 2. If Codec is set to MP3, valid values are 1 or 2. If Codec is set to AAC, valid values are 1, 2, 4, 5, 6, or 8.
Profile	String	No	The audio codec profile. If Codec is set to AAC, valid values include aac_low, aac_he, aac_he_v2, aac_ld, and aac_eld.
Volume	Volume	No	The volume configuration.

Example of the Audio parameter

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

Container: container format

Name

Type

Required

Description

Format

String

Yes

The container format.

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

Example of the Container parameter

{
        "Format":"mp4"
}

MuxConfig: HLS segment configuration

Note

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

Name	Type	Required	Description
Segment	Segment	Yes	A JSON object that contains segment configuration fields.

Segment: segment configuration details

Name

Type

Required

Description

Duration

String

Yes

The duration of each 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: average bitrate (ABR) mode. Encoding is faster than twopass. Alibaba Cloud uses onepass by default. twopass: variable bitrate (VBR) mode. The encoder runs twice to allocate bitrate precisely, producing smaller files with higher quality. Twopass takes longer than onepass and is unsuitable for latency-sensitive scenarios like live streaming or real-time communication. If the input video is highly compressed, twopass may cause blocking artifacts. CBR: constant bitrate mode. The file uses the same bitrate throughout. CBR files are larger than VBR or ABR files and offer no significant quality improvement. Default value: onepass.
IsCheckReso	String	No	Checks the source video resolution to determine whether to use the source resolution for transcoding. Valid values: true: checks the resolution. If the output resolution exceeds the source resolution (based on width or height), the output resolution is set to the source resolution. false: skips the check. Default value: false.
IsCheckResoFail	String	No	Checks the source video resolution to determine whether transcoding fails. Valid values: true: checks the resolution. If the output resolution exceeds the source resolution (based on width or height), transcoding fails. false: skips the check. Default value: false.
IsCheckVideoBitrate	String	No	Checks the source video bitrate to determine whether to use the source bitrate for transcoding. Valid values: true: checks the bitrate. If the output bitrate exceeds the source bitrate, the output bitrate is set to the source bitrate. false: skips the check. Default value: false.
IsCheckVideoBitrateFail	String	No	Checks the source video bitrate to determine whether transcoding fails. Valid values: true: checks the bitrate. If the output bitrate exceeds the source bitrate, transcoding does not occur. false: skips the check. Default value: false. This value takes precedence over IsCheckVideoBitrate.
IsCheckAudioBitrate	String	No	Checks the source audio bitrate to determine whether to use the source bitrate for transcoding. Valid values: true: checks the bitrate. If the output bitrate exceeds the source bitrate, the output bitrate is set to the source bitrate. false: skips the check. Default value: false.
IsCheckAudioBitrateFail	String	No	Checks the source audio bitrate to determine whether transcoding fails. Valid values: true: checks the bitrate. If the output bitrate exceeds the source bitrate, transcoding does not occur. false: skips the check. Default value: false. This value takes precedence over IsCheckAudioBitrate.

Example of the TransConfig parameter

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

Clip: video cropping configuration

Name	Type	Required	Description
TimeSpan	TimeSpan	Yes	The time-related configuration for video cropping.

TimeSpan: video cropping configuration

Name	Type	Required	Description
Seek	String	Yes	The start time of the video clip. 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. We recommend using Format 1.
Duration	String	No	Video clipping duration. 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. We recommend using Format 1. Note You must specify either Duration or End. If you specify both, End takes effect.
End	String	No	The duration of the trailing segment to discard during video clipping. 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. We recommend using Format 1. Note You must specify either Duration or End. If you specify both, End takes effect. The duration between the start and end times must not exceed the total video duration.

EncryptSetting: transcoding encryption configuration

Note

To use HLS standard encryption, you must first set the EncryptType parameter in the transcoding template to AliyunVoDEncryption. Then, you can call the Submit media transcoding jobs operation and configure the EncryptConfig parameter.

Name

Type

Required

Description

EncryptType

String

Yes

The encryption type. Valid values:

AliyunVoDEncryption: private encryption or HLS standard encryption for M3U8 (HLS) videos.
AliyunVoDLicenseEncryption: private encryption for MP4 videos.

Example of the EncryptSetting parameter

{
        "EncryptType":"AliyunVoDEncryption"
}

PackageSetting: transcoding packaging configuration

Note

You cannot package extracted audio and video streams.
Currently, only HLS adaptive bitrate packaging is supported.

Name	Type	Required	Description
PackageType	String	Yes	The packaging type. Valid value: HLSPackage (HLS adaptive bitrate packaging).
PackageConfig	PackageConfig	No	The packaging configuration. You must specify this parameter for a VideoPackage template.
SubtitleExtractConfigList	SubtitleExtractConfig[]	No	The subtitle packaging configuration. You must specify this parameter for a SubtitlePackage template. Do not specify it for other template types.

PackageConfig: video packaging configuration

Note

You must set this parameter only for HLS adaptive bitrate streaming packaging.

Name

Type

Required

Description

BandWidth

String

Yes

The maximum bandwidth. You must specify this parameter for HLS packaging. Unit: bps.

You must specify this parameter only for VideoPackage templates.

Example of the PackageSetting parameter

VideoPackage template configuration:
{
        "PackageType":"HLSPackage",
        "PackageConfig":{
                "BandWidth":"400000"
        }
}

SubtitleExtractConfig: subtitle 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. Subtitle files must be stored in buckets allocated by ApsaraVideo VOD.
Language	String	Yes	The language of the subtitle. For example, en-US. See RFC 5646 for more information.
Format	String	Yes	The subtitle file format. Only .vtt files are supported. For example: subtitle.vtt.
Name	String	Yes	The display name of the subtitle track in the player. For example: Chinese or English.

Example of the SubtitlePackage parameter

SubtitlePackage template configuration:
 {
      "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 pure CDN domain names are not supported. Supported subtitle formats: srt and ass.

Note

The subtitle file and the source video file must be in the same region (for example, China East 1) and the same bucket.

CharEncode

String

Yes

The character encoding format. Valid values:

auto: automatic detection.
UTF-8
GBK
BIG5

Default value: UTF-8.

Note

For more information about uploading subtitle files, 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: volume configuration

Name	Type	Required	Description
Method	String	No	The volume adjustment method. Valid values: auto, dynamic, linear.
IntegratedLoudnessTarget	String	No	The target loudness level. Valid values: [-70,-5]. Required if Method is set to dynamic. Default value: -6.
TruePeak	String	No	The maximum peak level. Valid values: [-9,0]. Required if Method is set to dynamic. Default value: -1.
LoudnessRangeTarget	String	No	The loudness range. Valid values: [1,20]. Required if 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 codecs

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

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

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

Supported combinations of video codecs and video stream configuration parameters

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

TranscodeSummary: transcoding summary

Name	Type	Description
VideoId	String	The ID of the video.
TranscodeTemplateGroupId	String	The ID of the transcoding template group used for transcoding.
TranscodeStatus	String	The transcoding status. Valid values: Processing: In progress. Partial: some transcoding jobs are complete. CompleteAllSucc: all transcoding jobs succeeded. CompleteAllFail: all transcoding jobs failed. If the source video has issues, no transcoding job starts and the entire task fails. CompletePartialSucc: all transcoding jobs completed, but only some succeeded.
TranscodeJobInfoSummaryList	TranscodeJobInfoSummary[]	The list of transcoding job summaries.
CreationTime	String	The time when the transcoding task was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
CompleteTime	String	The time when the transcoding task was completed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

TranscodeJobInfoSummary: summary of a transcoding job

Name	Type	Description
TranscodeTemplateId	String	The ID of the transcoding template used.
Width	String	The width of the output video. Unit: pixels.
Height	String	The height of the output video. Unit: pixels.
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 applied to the output video.
TranscodeProgress	Long	The transcoding progress. Valid values: [0,100].
TranscodeJobStatus	String	The status of the transcoding job. Valid values: Transcoding: the job is running. TranscodeSuccess: the job succeeded. TranscodeFail: Transcoding failed.
CreationTime	String	The time when the transcoding job was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
CompleteTime	String	The time when the transcoding job was completed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
ErrorCode	String	The error code returned if the transcoding job failed.
ErrorMessage	String	The error message returned if the transcoding job failed.

TranscodeTask: information about a transcoding task

Name	Type	Description
TranscodeTaskId	String	The ID of the transcoding task.
TranscodeTemplateGroupId	String	The ID of the transcoding template group used for transcoding.
VideoId	String	The ID of the video.
TaskStatus	String	The status of the transcoding task. Valid values: Processing: In progress. Partial: some transcoding jobs are complete. CompleteAllSucc: All transcoding tasks were completed successfully. CompleteAllFail: all transcoding jobs failed. If the source video has issues, no transcoding job starts and the entire task fails. CompletePartialSucc: all transcoding jobs completed, but only some succeeded.
CreationTime	String	The time when the transcoding task was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
CompleteTime	String	The time when the transcoding task was completed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
Trigger	String	The trigger type. Valid values: Auto: transcoding is triggered automatically after a video is uploaded. Manual: transcoding is triggered by calling the SubmitTranscodeJobs operation.
TranscodeJobInfoList	TranscodeJobInfo	The information about transcoding jobs.

TranscodeJobInfo: information about a transcoding job

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 job is running. TranscodeSuccess: the job succeeded. TranscodeFail: the job failed.
Priority	String	The priority of the transcoding task.
Definition	String	The definition. Note This value is the definition tag configured in the transcoding template. It does not represent the actual resolution range of the output video.
TranscodeTemplateId	String	The ID of the transcoding template used for transcoding.
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	The information about the output file.
ErrorCode	String	The error code returned if the transcoding job failed.
ErrorMessage	String	The error message returned if the transcoding job failed.

OutputFile: output file after transcoding

Name	Type	Description
OutputFileUrl	String	The OSS URL of the output file.
Format	String	The container format of the output file.
Width	String	The width of the video in the output file. Unit: pixels.
Height	String	The height of the video in 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 used for 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: Daily top video playback statistics

Name	Type	Description
VideoId	String	The video ID.
PlayDuration	String	The playback duration in milliseconds.
Title	String	The video title.
VV	String	The number of video views.
UV	String	Number of users playing back content.

VideoPlayStatisDetail: Daily playback statistics for a specific video

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

UserPlayStatisTotals: Daily total user playback statistics

Name	Type	Description
Date	String	The date in the yyyyMMdd format. Example: 20170120.
PlayDuration	String	The total playback duration in milliseconds.
PlayRange	String	The distribution of playback duration.
VV	VV	The total number of video views.
UV	UV	The total number of users who have played back content.

UserPlayStatisAvgs: Daily average user playback statistics

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

VV distribution

Statistics are collected only for playbacks that use Alibaba Cloud Video on Demand Player SDKs.

Name	Type	Description
Android	String	The total number of video views from the player for Android.
iOS	String	The total number of video views from the player for iOS.
Flash	String	Total number of playback sessions by the Flash player.
HTML5	String	The total number of video views from the player for HTML5.

Playback Count UV Distribution

Statistics are collected only for playbacks that use Alibaba Cloud Video on Demand Player SDKs.

Name	Type	Description
Android	String	The total number of unique visitors from the player for Android.
iOS	String	Total number of users who performed playback on the iOS player.
Flash	String	Total playback users on Flash Player
HTML5	String	Total number of users for HTML5 playback.

Event notifications

MessageCallback: Event notification configurations

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 endpoint of the MNS queue for MNS callbacks.
MnsQueueName	String	The name of the MNS queue for MNS callbacks.
EventTypeList	String	The callback event type.
AuthSwitch	String	The authentication switch for HTTP callbacks. Valid values: On: enable. off: Disabled.
AuthKey	String	The authentication key for HTTP callbacks.

Multi-application system

AppInfo: application information

Name	Type	Description
AppId	String	The application ID.
AppName	String	The application name.
Description	String	The application description.
Type	String	The application type. Valid values: The system is set to default. Custom: User-created.
Status	String	The application status. Valid values: Normal: Normal. Disable: The application is disabled.
CreationTime	String	The UTC creation time.
ModificationTime	String	The UTC update time.

AppPolicy: application authorization policy information

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