AddMedia-阿里云帮助中心

Creates a new media job.

Operation description

This API processes existing media files in OSS, eliminating the need to re-upload them. If you have configured a workflow, OSS automatically notifies MPS when a media file is uploaded to OSS. MPS then automatically executes a matching, active workflow based on the specified OSS bucket and Object. Therefore, you typically do not need to manually call the AddMedia API to process files.
An active workflow automatically retrieves media information when processing a media file. If you specify an inactive workflow or no workflow, media information is not retrieved.

QPS limit

The QPS limit for this API is 100 requests per second for a single user. If you exceed this limit, the system throttles your API calls. This may impact your business, so please plan your calls accordingly. 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 OSS URL of the input file. You can obtain this URL from the MPS console or the OSS console. For details about trigger rules, see the Workflow trigger matching rules. Only OSS HTTP URLs are supported. CDN and HTTPS URLs are not supported. The URL can be up to 3,200 bytes in length. The URL must be URL-encoded, in UTF-8, and compliant with RFC 2396. For more information, see URL Encoding.	http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
Title	string	No	The title of the media file. Maximum length: 128 bytes. UTF-8 encoded.	mytest
Description	string	No	The description of the media file. Maximum length: 1,024 bytes. UTF-8 encoded.	A test video
CoverURL	string	No	The URL of the media cover. You can obtain the URL in the MPS console (Workflow Management > Media Buckets) or the OSS console (My Access Paths). The URL can be up to 3,200 bytes in length. The URL must be URL-encoded, in UTF-8, and compliant with RFC 2396. For more information, see URL Encoding.	http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
Tags	string	No	A list of tags. Note In ApsaraVideo for Media Processing, each tag for a media file is independent. You can search the media library to find all media files that have the same tag. Separate multiple tags with a comma (,). You can add up to 16 tags. Each tag can be up to 32 bytes long. UTF-8 encoded.	tag1,tag2
MediaWorkflowId	string	No	The ID of the media workflow. You can find this ID in the MPS console or obtain it by calling the AddMediaWorkflow operation. Note This parameter queues an asynchronous task for background execution.	07da6c65da7f458997336e0de192****
MediaWorkflowUserData	string	No	User-defined data for the media workflow. Maximum length: 1,024 bytes. UTF-8 encoded.	test
InputUnbind	boolean	No	Specifies whether to check if the specified workflow supports the input path. Set this parameter to `true` to prevent errors from an invalid path. Valid values: true: Checks if the workflow supports the input path. false: Does not check if the workflow supports the input path.	false
CateId	integer	No	The ID of the category for the media file. This value cannot be negative.	123
OverrideParams	string	No	The override parameters, specified as a JSON string. Example 1: To override subtitles for HLS packaging: `{“WebVTTSubtitleOverrides”,[{“RefActivityName”:”subtitleNode”,”WebVTTSubtitleURL”:”http://test.oss-cn-hangzhou.aliyuncs.com/example1.vtt"}]}`. Example 2: To override subtitles for DASH packaging: `{“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

A workflow is triggered by prefix matching. The system compares the path of a newly added file against the path prefix configured for the workflow. If the file path starts with the configured prefix, it triggers the workflow. For example, for a file with the path http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test1.flv, the following rules apply:

1. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/          Match
2. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/            Match
3. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/              Match
4. http://bucket.oss-cn-hangzhou.aliyuncs.com/                Match
5. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.flv  Match
6. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/CC/         Does not match
7. http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B2/           Does not match
8. http://bucket.oss-cn-hangzhou.aliyuncs.com/A2/B/C/         Does not match

Note

To prevent a single file from triggering multiple workflow executions, do not configure the input path of one workflow as a prefix of another. For example, if you configure two workflows with the input paths test and test1, a file uploaded to the test1 directory will also match the test prefix, triggering both workflows.

Matching file extensions

ApsaraVideo Media Processing triggers workflows for multimedia files only. It identifies file types by their file extension. A file triggers a workflow if its extension is on the supported list, or if it has no extension (meaning the filename does not contain a period).

Note

For SWF files, the quality of snapshots and the transcoding service cannot be guaranteed.

Type	File extensions
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

A media workflow uses Message Service (MNS) to send notifications to your video cloud service application. The system sends a message when a Start or Report activity node completes. To receive these messages, you must specify a queue or topic name in the Start activity node. These messages are stored in the specified queue or topic, and you can retrieve them using the MNS SDK. The message format is as follows:

Parameter	Type	Description
RunId	String	The ID of the workflow execution.
Name	String	The name of the activity node.
Type	String	The type of the activity node. Valid values: `Start` and `Report`.
State	String	The state of the activity node. Valid values: `Success` and `Fail`.
Code	String	The error code. This field is present only when the `State` is `Fail`.
Message	String	A detailed description of the error, provided only if the `State` is `Fail`.
MediaWorkflowExecution	MediaWorkflowExecution	Information about the media workflow execution.

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	05F8B913-E9F3-4A6F-9922-48CADA0FFAAD
Media	object	Details of the media object.
CreationTime	string	The creation time.	2016-09-20T03:02:40Z
CateId	integer	The category ID.	1
Height	string	The height of the media file, in pixels.	1280
CensorState	string	The moderation status. Valid values: Initiated: The media is uploaded, but moderation is pending. Pass: The media is uploaded and has passed moderation.	Initiated
Tags	object	The tags.
Tag	array	The tags.
	string	A list of tags.	tag,tag2
Bitrate	string	The bitrate of the media file, in Kbit/s.	1148.77
MediaId	string	The media ID.	3e6149d5a8c944c09b1a8d2dc3e4****
File	object	The source file.
State	string	The status of the file. Default value: Normal.	Normal
URL	string	The file URL.	http://bucket.oss-cn-hangzhou.aliyuncs.com/A/B/C/test.mp4
PublishState	string	The publication status of the media, which indicates whether the media is publicly available. Valid values: Initiated: The initial state. UnPublish: The media is unpublished. The corresponding file in OSS has Private permissions. Published: The media is published. The corresponding file in OSS has Default permissions.	Published
Description	string	The description. The value can be up to 1,024 bytes in length.	A test video
Width	string	The width of the media file, in pixels.	1280
Size	string	The size of the media file, in bytes.	379860
CoverURL	string	The cover URL.	http://bucket.oss-cn-hangzhou.aliyuncs.com/example/1.png
RunIdList	object	The IDs of the media workflow execution instances.
RunId	array	The IDs of the media workflow execution instances.
	string	The IDs of the executed media workflow instances. Multiple IDs are separated by commas (,).	{"RunId":["cbad98d35629470fa05ff393d347****"]}
Duration	string	The duration of the media file, in seconds.	2.645333
Fps	string	The frame rate of the media file.	25.0
Title	string	The title of the media. The value can be up to 128 bytes in length.	mytest.mp4
Format	string	The format. Supported formats include 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.