UploadMediaByURL

Uploads audio or video media files by fetching them from source URLs. This operation supports batch uploads.

Operation description

Before calling this operation, ensure you understand the billing methods and pricing of ApsaraVideo for VOD. Uploading media asset files to ApsaraVideo for VOD incurs storage fees. For more information, see Media storage. If you have enabled storage transfer acceleration, uploading media asset files to ApsaraVideo for VOD also incurs upload acceleration fees. For more information, see storage transfer acceleration.
For a list of supported media formats, see Media formats.
Use this operation to upload files from a public URL instead of from a local server or device.
This is an asynchronous upload API. The operation does not complete in real time and has no guaranteed processing time. A job may take several hours or even days to complete. For faster uploads, use an upload SDK.
If you configure a callback, you receive an URLUploadComplete event notification after the upload completes. You can call the GetURLUploadInfos operation to query the upload status.
When you submit an upload job, the service creates an asynchronous task. The service queues URL upload jobs from all users in the same region. The time it takes to complete a job depends on the number of existing jobs. After the upload is complete, you can use the URL and video ID returned in the event notification to associate resources.
This operation is available only in the following regions: China (Shanghai), China (Beijing), China (Shenzhen), Singapore, and US (Silicon Valley).
Each time you submit an upload job for the same media file URL, ApsaraVideo for VOD creates a new media resource with a new media ID.
If a single file exceeds 20 GB, the upload fails. If you need to upload files larger than 20 GB, use an upload SDK. For more information, see Overview of upload SDKs.

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:UploadMediaByURL

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
UploadURLs	string	Yes	The URLs of the source media files. The URL must include the file extension. For example, mp4 is the file extension in `https://**.mp4`. If the URL does not contain a file extension, you can specify one by setting the `FileExtension` parameter in `UploadMetadatas`. If you specify a file extension in both the URL and the `FileExtension` parameter, the value of the `FileExtension` parameter takes precedence. For a list of supported file extensions, see Overview of uploads. Note You can specify up to 20 URLs. Separate multiple URLs with commas (,). To prevent upload failures caused by special characters, you must URL-encode** each URL before you concatenate them with commas.	https://****.mp4
TemplateGroupId	string	No	The ID of the transcoding template group. You can obtain the ID in one of the following ways: Log on to the ApsaraVideo for VOD console. In the left-side navigation pane, choose Configuration Management > Media Processing > Transcoding Template Groups to view the transcoding template group ID. The value of `TranscodeTemplateGroupId` in the response to the AddTranscodeTemplateGroup operation. The value of `TranscodeTemplateGroupId` in the response to the ListTranscodeTemplateGroup operation. Note If you do not specify this parameter, the default transcoding template group is used. If you specify this parameter, the specified transcoding template group is used. You can also set this parameter in `UploadMetadatas`. If you set `TemplateGroupId` in both `UploadMetadatas` and at this level, the `TemplateGroupId` in `UploadMetadatas` takes precedence.	ca3a8f6e4957b65806709586****
StorageLocation	string	No	The storage location of the media file. Log on to the ApsaraVideo for VOD console. In the left-side navigation pane, choose Configuration Management > Media Asset Management > Storage to view the storage location. If you do not specify this parameter, the default storage location is used.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
UploadMetadatas	string	No	The metadata of the media file to be uploaded. The value must be a JSON string. This parameter takes effect only when it matches a URL in `UploadURLs`. The value must be a JSON string that represents an array of `UploadMetadata` objects. For more information, see the UploadMetadata table below.	[{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
UserData	string	No	Custom settings. The value must be a JSON string. This parameter supports features such as message callbacks and upload acceleration. For more information, see UserData. Note To use message callbacks, you must configure an HTTP callback URL and select the corresponding event types in the console. Otherwise, the callback settings do not take effect. For more information about how to configure HTTP callbacks in the console, see Callback settings. To use the upload acceleration feature, you must submit a ticket to enable it. For more information, see Upload-related notes. For information on how to submit a ticket, see Contact us.	{"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
AppId	string	No	The application ID. The default value is app-1000000. For more information, see Multi-application service.	app-****
WorkflowId	string	No	The workflow ID. To view the workflow ID, log on to the ApsaraVideo for VOD console. In the left-side navigation pane, choose Configuration Management > Media Processing > Workflows. Note If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence. For more information, see Workflows.	e1e243b42548248197d6f74f9****
SessionId	string	No	A custom deduplication identifier. If you specify this parameter in a request, the service returns an error if a request with the same identifier is repeated within 10 minutes. Note You can customize the identifier. The identifier can be up to 50 characters in length and can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). If you do not specify this parameter or pass an empty string, the service does not perform deduplication.	5c62d40299034bbaa4c195da330****
EnableFirstFrameCover	boolean	No
GenerateThumbnail	boolean	No

UploadMetadata

Parameter	Type	Required	Description
SourceURL	String	Yes	The URL of the source media file to be uploaded.
Title	String	No	The title of the media file. The title can be up to 128 bytes in length and must be UTF-8 encoded.
FileSize	String	No	The size of the file.
Description	String	No	The description of the media file. The description can be up to 1,024 bytes in length and must be UTF-8 encoded.
CoverURL	String	No	The URL of a custom video cover.
CateId	String	No	The category ID. To view the category ID, log on to the ApsaraVideo for VOD console. In the left-side navigation pane, choose Configuration Management > Media Asset Management > Categories.
Tags	String	No	The tags of the media file. A single tag can be up to 32 bytes in length. You can specify a maximum of 16 tags. Separate multiple tags with commas (,). The tags must be UTF-8 encoded.
TemplateGroupId	String	No	The ID of the transcoding template group. This parameter overrides the `TemplateGroupId` specified at the top level of the request.
WorkflowId	String	No	The ID of the workflow. If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence. For more information, see Workflows.
FileExtension	String	No	The file extension of the media file. For a list of supported file extensions, see Overview of uploads.
ReferenceId	String	No	A custom ID. The ID can be 6 to 64 characters in length and can contain letters, digits, hyphens (-), and underscores (_). The ID must be unique within your account.

Note

Parameters in UploadMetadata, such as Title, Description, and Tags, cannot contain emojis.
To ensure proper playback when transcoding is disabled (by setting TemplateGroupId to VOD_NO_TRANSCODE), only files in MP4, FLV, MP3, M3U8, and WEBM formats can be played directly after upload. Other formats are supported for storage only. The system checks the file extension. If you use Alibaba Cloud Player, its version must be 3.1.0 or later.
If you specify a transcoding-disabled template group (TemplateGroupId is set to VOD_NO_TRANSCODE), you receive only an event notification for VideoUploadComplete after the video is uploaded. You do not receive an event notification for TranscodeComplete.
If a callback is configured, you will receive an URLUploadComplete event notification in addition to upload and transcoding notifications after the video is uploaded.
For batch submissions, the service sends a separate notification for each SourceURL.

Response elements

Element	Type	Description	Example
	object	The response that is returned.
RequestId	string	The request ID.	25818875-5F78-4AF6-D7393642CA58****
UploadJobs	array<object>	A list of upload jobs.
	object	The details of the upload job.
SourceURL	string	The source URL of the file in the upload job.	http://example****.mp4
JobId	string	The ID of the upload job.	ad90a501b1b94fb72374ad005046****

Examples

Success response

JSON format

{
  "RequestId": "25818875-5F78-4AF6-D7393642CA58****",
  "UploadJobs": [
    {
      "SourceURL": "http://example****.mp4",
      "JobId": "ad90a501b1b94fb72374ad005046****"
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.