SubmitMediaProducingJob - Intelligent Media Services

Submits a media editing and production job. If you need to perform any form of post-production such as editing and production on video or audio materials, you can call this operation to automate the process.

Operation description

This operation returns only the submission result of a media editing and production job. When the submission result is returned, the job may still be in progress. After a media editing and production job is submitted, the job is queued in the background for asynchronous processing.
The materials referenced in the timeline of an online editing project can be media assets in the media asset library or Object Storage Service (OSS) objects. External URLs or Alibaba Cloud Content Delivery Network (CDN) URLs are not supported. To use an OSS object as a material, you must set MediaUrl to an OSS URL, such as https://your-bucket.oss-region-name.aliyuncs.com/your-object.ext.
After the production is complete, the output file is automatically registered as a media asset. The media asset first needs to be analyzed. After the media asset is analyzed, you can query the duration and resolution information based on the media asset ID.

Limits

The throttling threshold of this operation is 30 queries per second (QPS).

**

Note If the threshold is exceeded, a "Throttling.User" error is returned when you submit an editing job. For more information about how to resolve this issue, see the FAQ .
You can create up to 100 video tracks, 100 image tracks, and 100 subtitle tracks in a project.
The total size of material files cannot exceed 1 TB.
The OSS buckets in which the materials reside and where the output media assets are stored must be in the same region as the region in which Intelligent Media Services (IMS) is activated.
An output video must meet the following requirements:
- Both the width and height must be at least 128 pixels.
- Both the width and height cannot exceed 4,096 pixels.
- The shorter side of the video cannot exceed 2,160 pixels.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
ice:SubmitMediaProducingJob		All Resources ``	none	none

Request parameters

Parameter	Type	Required	Description	Example
ProjectId	string	No	The ID of the editing project. Note : You must specify one of ProgectId, Timeline, and TempalteId and leave the other two parameters empty.	xxxxxfb2101cb318xxxxx
Timeline	string	No	The timeline of the online editing job. For more information about the parameters, see Timeline configurations. Note : You must specify one of ProgectId, Timeline, and TempalteId and leave the other two parameters empty.	{"VideoTracks":[{"VideoTrackClips":[{"MediaId":"**4d7cf14dc7b83b0e801c"},{"MediaId":"4d7cf14dc7b83b0e801c**"}]}]}
TemplateId	string	No	The template ID. The template is used to build a timeline with ease. Note : You must specify one of ProgectId, Timeline, and TempalteId and leave the other two parameters empty. If TemplateId is specified, ClipsParam must also be specified.	**96e8864746a0b6f3**
ClipsParam	string	No	The material parameters of the template, in the JSON format. If TemplateId is specified, ClipsParam must also be specified. For more information, see Create and use a regular template and Create and use advanced templates.
ProjectMetadata	string	No	The metadata of the editing project, in the JSON format. For more information about the parameters, see ProjectMetadata .
OutputMediaTarget	string	No	The type of the output file. Valid values: oss-object: OSS object in an OSS bucket. vod-media: media asset in ApsaraVideo VOD. S3: output file based on the Amazon Simple Storage Service (S3) protocol.	oss-object
OutputMediaConfig	string	Yes	The configurations of the output file, in the JSON format. You can specify an OSS URL or a storage location in a storage bucket of ApsaraVideo VOD. To store the output file in OSS, you must specify MediaURL. To store the output file in ApsaraVideo VOD, you must specify StorageLocation and FileName. For more information, see OutputMediaConfig .	{"MediaURL":"https://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4"}
UserData	string	No	The user-defined data in the JSON format, which can be up to 512 bytes in length. You can specify a custom callback URL. For more information, see Configure a callback upon editing completion.	{"NotifyAddress":"https://xx.com/xx","RegisterMediaNotifyAddress":"https://xxx.com/xx"}
ClientToken	string	No	The client token that is used to ensure the idempotence of the request.	**12e8864746a0a398**
Source	string	No	The source of the editing and production request. Valid values: OpenAPI AliyunConsole WebSDK	OPENAPI
EditingProduceConfig	string	No	The parameters for editing and production. For more information, see EditingProduceConfig . Note If no thumbnail is specified in EditingProduceConfig, the first frame of the video is used as the thumbnail. AutoRegisterInputVodMedia: specifies whether to automatically register the ApsaraVideo VOD media assets in your timeline with IMS. Default value: true. OutputWebmTransparentChannel: specifies whether the output video contains alpha channels. Default value: false. CoverConfig: the custom thumbnail parameters.	{ "AutoRegisterInputVodMedia": "true", "OutputWebmTransparentChannel": "true" }
MediaMetadata	string	No	The metadata of the produced video, in the JSON format. For more information about the parameters, see MediaMetadata .	{ "Title":"test-title", "Tags":"test-tags1,tags2" }

Sample OutputMediaConfig parameter configurations.

Example: Store the output file in OSS

{
  "MediaURL":"https://my-test-bucket.oss-cn-shanghai.aliyuncs.com/test/xxxxxtest001xxxxx.mp4",
  "Bitrate": 2000,  
  "Width": 800,  
  "Height": 680
}

To store the output file in OSS, you must specify MediaURL. The default value of OutputMediaTarget is oss-object, which specifies to store the output file in OSS. Other parameters are optional. Bitrate specifies the bitrate of the output file. Generally, the higher the bitrate, the clearer the video. The maximum value is 5000. Width and Height specify the resolution of the output file.

Specify the OSS URL in the following format: https://bucketname.oss-region-name.aliyuncs.com/xxx/yyy.ext.

bucketname: the name of the OSS bucket.

region-name.aliyuncs.com: the public endpoint of OSS. For example, the endpoints of the China (Shanghai), China (Beijing), and China (Hangzhou) regions are:

oss-cn-shanghai.aliyuncs.com
oss-cn-hangzhou.aliyuncs.com 
oss-cn-beijing.aliyuncs.com

Example: Store the output file in ApsaraVideo VOD

{ 
  "StorageLocation": "outin-*xxxxxx7d2a3811eb83da00163exxxxxx.oss-cn-shanghai.aliyuncs.com",  
  "FileName": "output.mp4",  
  "Bitrate": 2000,  
  "Width": 800,  
  "Height": 680
}

To store the output file in ApsaraVideo VOD, you must specify StorageLocation and FileName. Set OutputMediaTarget to vod-media, which specifies to store the output file in a storage bucket of ApsaraVideo VOD. The storage locations that can be used in ApsaraVideo VOD can be found in the storage addresses for media assets after media assets are uploaded to ApsaraVideo VOD.

Parameters in OutputMediaConfig

Parameter	Type	Description
MediaURL	String	The URL of the output file. If OutputMediaTarget is set to oss-object, specify the HTTP URL of the OSS object, such as http://xxx-bucket-name.oss-cn-shanghai.aliyuncs.com/OSS. The region is the same as the region in which the operation is called.
StorageLocation	String	If OutputMediaTarget is set to vod-media, this parameter indicates the storage location of the media asset in ApsaraVideo VOD. The storage location is the path of the file in ApsaraVideo VOD, excluding the prefix http://. Example: outin-xxxxxx.oss-cn-shanghai.aliyuncs.com.
FileName	String	If OutputMediaTarget is set to vod-media, this parameter indicates the file name of the output file. The value contains the file name extension but not the path.
Width	Integer	The width of the output file. You can leave this parameter empty. The default value is the maximum width of the input materials.
Height	Integer	The height of the output file. You can leave this parameter empty. The default value is the maximum height of the input materials.
Bitrate	Integer	The bitrate of the output file. Unit: Kbit/s. You can leave this parameter empty. The default value is the maximum bitrate of the input materials.
VodTemplateGroupId	String	The ID of the VOD transcoding template group. If VOD transcoding is not required, set the value to VOD_NO_TRANSCODE.

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	**36-3C1E-4417-BDB2-1E034F**
ProjectId	string	The ID of the editing project.	**b4549d46c88681030f6e**
JobId	string	The job ID.	**d80e4e4044975745c14b**
MediaId	string	The media asset ID of the output file.	**c469e944b5a856828dc2**
VodMediaId	string	The media asset ID of the output file in ApsaraVideo VOD if the output file is stored in ApsaraVideo VOD.	**d8s4h75ci975745c14b**

Examples

Sample success responses

JSONformat

{
  "RequestId": "****36-3C1E-4417-BDB2-1E034F****",
  "ProjectId": "****b4549d46c88681030f6e****",
  "JobId": "****d80e4e4044975745c14b****",
  "MediaId": "****c469e944b5a856828dc2****",
  "VodMediaId": "****d8s4h75ci975745c14b****"
}

Error codes

HTTP status code	Error code	Error message
400	InvalidParameter	The specified parameter \ is not valid.
404	ProjectNotFound	The specified project not found

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2023-11-23	The Error code has changed	View Change Details
2023-04-25	The Error code has changed. The request parameters of the API has changed	View Change Details
2021-11-16	The Error code has changed. The request parameters of the API has changed. The response structure of the API has changed	View Change Details