Call AddMedia to add a media file - ApsaraVideo Media Processing - Alibaba Cloud - ApsaraVideo Media Processing

Submits a job to add media.

Operation description

If you have existing videos stored in OSS, you can use this operation to process them without re-uploading the videos to OSS. If you have configured a media workflow, OSS automatically notifies ApsaraVideo Media Processing after a media file is uploaded to OSS. Based on the configured OSS bucket and object, the system automatically matches and runs active workflows. Therefore, you do not need to manually call the AddMedia operation to process files in most cases.
Media information is automatically obtained only when you specify an active workflow to process media files. If you do not specify a workflow or specify a workflow in another state, media information is not obtained.

QPS limit

The QPS limit for a single user for this operation is 100 calls per second. If the limit is exceeded, the API call is throttled, which may affect your business. Call this operation properly. For more information, see QPS limit.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

mts:AddMedia

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
FileURL	string	Yes	The path of the input file. You can obtain the path from the ApsaraVideo Media Processing or OSS console. For detailed trigger rules, see Workflow trigger matching rules below. Only OSS HTTP addresses are supported. CDN addresses and HTTPS addresses are not supported. The value cannot exceed 3,200 bytes. The URL must comply with RFC 2396 (UTF-8 encoded and URL-encoded). For more information, see URL encoding.	http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
Title	string	No	The media title. The value cannot exceed 128 bytes. UTF-8 encoded.	mytest
Description	string	No	The description. The value cannot exceed 1,024 bytes. UTF-8 encoded.	A test video
CoverURL	string	No	The cover URL. This is the storage address of the cover that you want to set. You can obtain the address from ApsaraVideo Media Processing console > Workflow Management > Media Bucket or OSS console > My Access Path. The value cannot exceed 3,200 bytes. The URL must comply with RFC 2396 (UTF-8 encoded and URL-encoded). For more information, see URL encoding.	http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
Tags	string	No	The list of tags. Note In ApsaraVideo Media Processing, each tag of each media is independent. You can search the Media Library to find all media that have the same tag. Separate multiple tags with commas (,). A maximum of 16 tags are supported. Each tag cannot exceed 32 bytes. UTF-8 encoded.	tag1,tag2
MediaWorkflowId	string	No	The media workflow ID. You can obtain the ID from the ApsaraVideo Media Processing console or by calling the AddMediaWorkflow operation. Note This parameter task is an asynchronous task. After submission, the task is not completed immediately and is queued for asynchronous execution in the background.	07da6c65da7f458997336e0de192****
MediaWorkflowUserData	string	No	The custom data of the media workflow. The value cannot exceed 1,024 bytes. UTF-8 encoded.	test
InputUnbind	boolean	No	Specifies whether to check that the specified workflow supports the input path. Set this parameter to true to avoid errors caused by incorrect paths. Valid values: true: Check. false: Do not check.	false
CateId	integer	No	The category ID of the media. Negative values are not allowed.	123
OverrideParams	string	No	The override parameters. Example 1: HLS packaging caption override `{"WebVTTSubtitleOverrides",[{"RefActivityName":"subtitleNode","WebVTTSubtitleURL":"http://test.oss-cn-hangzhou.aliyuncs.com/example1.vtt"}]}`. Example 2: DASH packaging caption override `{"subtitleTransNodeName":{"InputConfig":{"Format":"stl","InputFile":{"URL":"http://subtitleBucket.oss-cn-hangzhou.aliyuncs.com/package/example/CENG.stl"}}}}`.	{“subtitleTransNodeName”:{“InputConfig”:{“Format”:”stl”,”InputFile”:{“URL”:”http://exampleBucket.oss-cn-hangzhou.aliyuncs.com/package/example/CENG.stl"}}}}

Workflow trigger matching rules

The rule matching execution policy is as follows: based on the path of the new file, the system checks the location bound to the workflow. If the path of the new file contains the string bound to the rule, the rule is matched. Otherwise, the rule is not matched. For example, for http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test1.flv, the rules are:

1、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/          Matched
2、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/            Matched
3、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/              Matched
4、http://bucket.oss-cn-hangzhou.aliyuncs.com/                Matched
5、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.flv  Matched
6、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/CC/         Not matched
7、http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B2/           Not matched
8、http://bucket.oss-cn-hangzhou.aliyuncs.com/A2/B/C/         Not matched

Note

When you add a media workflow, do not configure the input path of one workflow as a prefix of the input path of another workflow. Otherwise, a single incremental file triggers two workflow execution instances. For example, if the input paths of two workflows are configured as test and test1, when an input file is uploaded to the test1 folder, it also matches the test prefix, triggering two workflow execution instances.

Matching file name extensions

The trigger requires multimedia files. The Media Library determines file types by file name extensions. A file either has no file name extension (the file name does not contain the extension separator ".") or has a file name extension that complies with the following rules:

Note

For SWF files, the quality of snapshot and transcoding services is not guaranteed.

Type	Extension
Video	3gp, asf, avi, dat, dv, flv, f4v, gif, m2t, m3u8, m4v, mj2, mjpeg, mkv, mov, mp4, mpe, mpg, mpeg, mts, ogg, qt, rm, rmvb, swf, ts, vob, wmv, webm
Audio	aac, ac3, acm, amr, ape, caf, flac, m4a, mp3, ra, wav, wma, aiff

Media workflow messages

Media workflows use Alibaba Cloud Simple Message Queue (formerly MNS) to send messages to video cloud service consumers. A media workflow sends messages when Start or Report activity nodes are completed. To receive messages, set the queue or notification name on the Start activity. Messages generated by the media workflow are stored in the queue or notification. You can use the Simple Message Queue (formerly MNS) SDK to retrieve messages. The message specifications are as follows:

Name	Type	Description
RunId	String	The workflow execution ID.
Name	String	The activity name.
Type	String	The activity type. Valid values: Report, Start.
State	String	The activity status. Valid values: Fail, Success.
Code	String	The error code. A specific error code is returned if the activity status is Fail.
Message	String	The error message. A detailed error description is returned if the activity status is Fail.
MediaWorkflowExecution	MediaWorkflowExecution	The media workflow execution information.

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	05F8B913-E9F3-4A6F-9922-48CADA0FFAAD
Media	object	The media information.
CreationTime	string	The creation time.	2016-09-20T03:02:40Z
CateId	integer	The category ID.	1
Height	string	The height of the media file.	1280
CensorState	string	The video moderation status. Valid values: Initiated: Initiated. The video is uploaded but moderation is not completed. Pass: Passed. The video is uploaded and has passed moderation.	Initiated
Tags	object
Tag	array	The tag.
	string	The list of tags.	tag,tag2
Bitrate	string	The bitrate.	1148.77
MediaId	string	The media ID.	3e6149d5a8c944c09b1a8d2dc3e4****
File	object	The original file.
State	string	The file status. The default value is Normal.	Normal
URL	string	The file URL.	http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
PublishState	string	The media publish status, which indicates whether the media is published externally. Valid values: Initiated: Initiated. UnPublish: Unpublished. The OSS playback file permission is Private. Published: Published. The OSS playback file permission is Default.	Published
Description	string	The description. The value cannot exceed 1,024 bytes.	A test video
Width	string	The width of the media file.	1280
Size	string	The size of the media file.	379860
CoverURL	string	The cover URL.	http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
RunIdList	object
RunId	array	The list of media workflow execution instance IDs.
	string	The list of executed media workflow execution instance IDs, separated by commas (,).	{"RunId":["cbad98d35629470fa05ff393d347****"]}
Duration	string	The duration of the media file.	2.645333
Fps	string	The frame rate of the media file.	25.0
Title	string	The media title. The value cannot exceed 128 bytes.	mytest.mp4
Format	string	The format. Supported formats: mov, mp4, m4a, 3gp, 3g2, and mj2.	mp4

Examples

Success response

JSON format

{
  "RequestId": "05F8B913-E9F3-4A6F-9922-48CADA0FFAAD",
  "Media": {
    "CreationTime": "2016-09-20T03:02:40Z",
    "CateId": 1,
    "Height": "1280",
    "CensorState": "Initiated",
    "Tags": {
      "Tag": [
        "tag,tag2"
      ]
    },
    "Bitrate": "1148.77",
    "MediaId": "3e6149d5a8c944c09b1a8d2dc3e4****",
    "File": {
      "State": "Normal",
      "URL": "http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4"
    },
    "PublishState": "Published",
    "Description": "A test video",
    "Width": "1280",
    "Size": "379860",
    "CoverURL": "http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png",
    "RunIdList": {
      "RunId": [
        "{\"RunId\":[\"cbad98d35629470fa05ff393d347****\"]}"
      ]
    },
    "Duration": "2.645333",
    "Fps": "25.0",
    "Title": "mytest.mp4",
    "Format": "mp4"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.