SubmitTranscodeJobs

Call this API to submit media transcoding jobs and start asynchronous transcoding.

Operation description

Usage notes

Media transcoding is a paid feature. Before you call this API, make sure that you are familiar with the billing methods and pricing of ApsaraVideo VOD. For more information, see Media Transcoding Billing.
This is an asynchronous API. The job is queued in the background for asynchronous processing. The result is sent through a callback. You can also query the job status by calling the GetTaskDetails operation.
You can start a transcoding job only for videos that are in the Uploaded, Normal, or Under Review state.
To get the transcoding result, you can receive message callbacks for the following events: Single Transcoding Job Complete and All Transcoding Jobs Complete.
This API supports dynamic replacement of subtitle URLs in HLS adaptive bitrate streaming packaging jobs. If a packaging job does not require subtitle processing, do not use this API. Instead, specify the corresponding packaging template group ID when you upload the video to automatically trigger the packaging process.

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

vod:SubmitTranscodeJobs

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
VideoId	string	No	The ID of the video. You can get the video ID in one of the following ways: For videos uploaded to the ApsaraVideo VOD console, log on to the ApsaraVideo VOD console and choose Media Files > Audio/Video to view the video ID. When you upload a video by calling the CreateUploadVideo API, the video ID is the value of the `VideoId` parameter in the response. After a video is uploaded, you can call the SearchMedia API to query the video ID, which is the value of the `VideoId` parameter in the response.	142710f878bd42508932f660d7b1****
TemplateGroupId	string	Yes	The ID of the transcoding template group to use for media transcoding. To view the template group ID, log on to the ApsaraVideo VOD console and choose Configuration Management >Media Processing Settings > Transcoding Template Group.	0e408c803baf658ee637790c5d9f****
PipelineId	string	No	The ID of the pipeline.	d3e680e618708erf45fbf2cae7c****
EncryptConfig	string	No	The encryption configuration, specified as a JSON string. This parameter is required only for HLS standard encryption. Note The CipherText parameter in the EncryptConfig structure must be an AES_128 ciphertext key generated by calling the GenerateKMSDataKey API. Otherwise, the HLS standard encryption transcoding job fails. For more information about how to implement HLS standard encryption, see HLS Standard Encryption. For both HLS standard encryption and private encryption, you must select the HLS encryption option in the template that corresponds to the specified TemplateGroupId. Otherwise, the output video is not encrypted.	{"CipherText":"ZjJmZGViNzUtZWY1Mi00Y2RlLTk3**", "DecryptKeyUri":"http://demo.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3**","KeyServiceType":"KMS"}
OverrideParams	string	No	Override parameters, specified as a JSON string. You can use this parameter to override settings in the transcoding template, including the image watermark file, text watermark content, subtitle file URL, and subtitle file encoding format. For details about the parameter structure, see OverrideParams.	{"Watermarks":[{"WatermarkId":"af2afe4761992c47dae973374**","FileUrl":"http://developer.aliyundoc.com/image/image.png"},{"WatermarkId":"e8e5b8038d7ada85b376c2707**","Content":"watermark test"}]}
Priority	string	No	The priority of the transcoding job in the queue. Valid values: 1 to 10. A value of 10 indicates the highest priority. Default value: 6. Note This parameter affects only the priority of the current transcoding job among all queued jobs. It does not affect the priority of jobs that are being processed.	6
UserData	string	No	Custom settings, specified as a JSON string. You can configure settings such as message callbacks. For more information, see UserData. Note To use the message callback feature, you must first configure an HTTP callback URL and select the corresponding event types in the console. Otherwise, the callback settings do not take effect.	{"Extend":{"localId":"**","test":"*"}}
SessionId	string	No	A custom idempotency key. If you submit a request with the same idempotency key within seven days, the request fails and an error is returned. The key can be up to 50 characters in length and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). If you do not specify this parameter or pass an empty string, the system does not deduplicate the request.	5c62d40299034bbaa4c195da330****
ReferenceId	string	No	A custom ID that must be unique for each user. The ID can be 6 to 64 characters long and can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_).	123-123

Response elements

Element	Type	Description	Example
	object	The response body.
TranscodeTaskId	string	The ID of the submitted transcoding task.	9f4a0df7da2c8a81c8c0408c84****
RequestId	string	The request ID.	E4EBD2BF-5EB0-4476-8829-9D94E1B1****
TranscodeJobs	object	The list of transcoding jobs.
TranscodeJob	array<object>	Details of the media transcoding jobs. Note This parameter is not returned for HLS adaptive bitrate streaming packaging jobs. You must receive asynchronous callbacks to handle the results.
	object	Details of a transcoding job.
JobId	string	The job ID. Note This parameter is not returned for HLS adaptive bitrate streaming packaging jobs. You must receive asynchronous callbacks to handle the results.	d8921ce8505716cfe86fb112c4****

Examples

Success response

JSON format

{
  "TranscodeTaskId": "9f4a0df7da2c8a81c8c0408c84****",
  "RequestId": "E4EBD2BF-5EB0-4476-8829-9D94E1B1****",
  "TranscodeJobs": {
    "TranscodeJob": [
      {
        "JobId": "d8921ce8505716cfe86fb112c4****"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.