SubmitTranscodeJobs-阿里云帮助中心

Submits a media transcoding job to start asynchronous transcoding.

Operation description

Usage notes

Before you call this operation, make sure that you fully understand the billing methods and pricing of ApsaraVideo VOD. Transcoding is a paid feature. For billing details, see Billing of media asset transcoding.
This operation is an asynchronous operation. After you submit a job, a job ID is returned. The job is not completed at this time and enters the background queue for asynchronous execution. The final result is notified through a callback. You can also call the Get job details operation to actively query the job status.
Only videos in the Upload Completed, Normal, or Under Review state can be transcoded.
To obtain the transcoding result, you can receive callback messages: Transcoding completed for a single definition and All transcoding completed.
This operation supports dynamic replacement of subtitle URLs in HLS adaptive bitrate streaming packaging jobs. If the packaging job does not involve subtitle packaging, we do not recommend using this operation to initiate the job. Instead, we recommend setting the corresponding packaging template group ID when uploading the video to automatically initiate 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 video ID. You can obtain the video ID by using one of the following methods: For videos uploaded through the console, log on to the ApsaraVideo VOD console and choose Media Assets > Audio/Video to view the video ID. When you call the CreateUploadVideo operation to upload a video, the video ID is the value of the VideoId response parameter. After a video is uploaded, you can call the SearchMedia operation to query the video ID. The video ID is the value of the VideoId response parameter.	142710f878bd42508932f660d7b1****
TemplateGroupId	string	Yes	The ID of the transcoding template group used for video transcoding. To use a specified template group for transcoding, log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing Configuration > Transcoding Template Groups to view the template group ID.	0e408c803baf658ee637790c5d9f****
PipelineId	string	No	The pipeline ID.	d3e680e618708erf45fbf2cae7c****
EncryptConfig	string	No	The encryption configuration. The value is a JSON string. This parameter is required only when HLS encryption is used. Note The CipherText parameter in the EncryptConfig struct must be an AES_128 ciphertext key generated by calling the GenerateKMSDataKey operation. Otherwise, standard encryption transcoding fails. For more information about the standard encryption integration process, see HLS encryption. For both standard encryption and proprietary encryption, you must select the HLS encryption option in the template data corresponding to TemplateGroupId. Otherwise, encryption is not performed.	{"CipherText":"ZjJmZGViNzUtZWY1Mi00Y2RlLTk3**", "DecryptKeyUri":"http://demo.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3**","KeyServiceType":"KMS"}
OverrideParams	string	No	The override parameters. The value is a JSON string. This parameter allows you to override the specified image watermark file, text watermark content, subtitle file URL, and subtitle file encoding format associated with the transcoding template. For more information 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 current transcoding job among all queued jobs. Valid values: 1 to 10. Highest priority: 10. Default value: 6. Note The Priority parameter only affects the priority of the current transcoding job among all queued jobs, but does not affect the priority of jobs that are already being processed.	6
UserData	string	No	The custom settings. The value is a JSON string. This parameter supports settings such as message callbacks. For more information, see UserData. Note To use message callbacks in this parameter, you must configure an HTTP callback URL and select the corresponding callback event types in the console. Otherwise, the callback settings do not take effect.	{"Extend":{"localId":"**","test":"*"}}
SessionId	string	No	The custom deduplication token. If a request with the same token was made within the last 7 days, the current request returns an error. The token can be up to 50 characters in length and can contain letters, digits, hyphens (-), and underscores (_). If you do not specify this parameter or specify an empty string, deduplication is not performed.	5c62d40299034bbaa4c195da330****
ReferenceId	string	No	The custom ID. The ID can be 6 to 64 characters in length and can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be unique per user.	123-123

Response elements

Element	Type	Description	Example
	object	The response result.
TranscodeTaskId	string	The ID of the submitted transcoding job.	9f4a0df7da2c8a81c8c0408c84****
RequestId	string	The request ID.	E4EBD2BF-5EB0-4476-8829-9D94E1B1****
TranscodeJobs	object
TranscodeJob	array<object>	The media job information. Note This parameter is not returned for HLS adaptive bitrate streaming packaging jobs. You must asynchronously receive the callback processing result.
	object	The media job details.
JobId	string	The job ID. Note This parameter is not returned for HLS adaptive bitrate streaming packaging jobs. You must asynchronously receive the callback processing result.	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.