UploadMediaByURL-阿里云帮助中心

Pulls and uploads audio and video media files from source URLs. Supports batch uploads.

Operation description

Before you call this operation, make sure that you fully understand the billing methods and pricing of ApsaraVideo VOD. Uploading media assets to ApsaraVideo VOD incurs storage fees. For billing details, see Media asset storage billing. If you have enabled storage transfer acceleration, uploading media assets to ApsaraVideo VOD also incurs upload acceleration fees. For billing details, see Storage transfer acceleration billing.
For the media file formats supported by this operation, see Media formats.
This operation is mainly applicable to scenarios where files are not stored on local servers or terminals and need to be uploaded through URLs with public network access.
This operation is an asynchronous upload operation. It is not real-time and does not guarantee timeliness. Generally, the migration and upload are completed within hours or even days after submission. If you have high requirements for timeliness, use the upload SDK.
If a callback is configured, you will receive a URL-based video upload complete event notification after the upload is complete. You can query the upload status by calling the Get URL upload information operation.
After an upload task is submitted, an asynchronously executed task is generated in the cloud. URL upload tasks submitted by all users in the corresponding service region are queued for execution. The completion time is affected by the number of existing tasks. After the upload is complete, you can associate the task based on the URL and video ID returned in the event notification (message callback).
This operation is currently supported only in the China (Shanghai), China (Beijing), China (Shenzhen), Singapore, and US (Silicon Valley) regions.
For the same media file URL, each submitted upload task generates a new media asset in ApsaraVideo VOD (that is, a new media ID is generated).
If a single file exceeds 20 GB, it will result in a failed upload. If you need to upload a single file larger than 20 GB, use the upload SDK. For more information, see Overview of the upload SDK.

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 a file name extension. For example, in `https://**.mp4`, mp4 is the file name extension. If the URL does not contain a file name extension, you can specify it by passing `FileExtension` in `UploadMetadatas`. If the URL contains a file name extension and `FileExtension` is also passed, the passed `FileExtension` prevails. For supported file name extensions, see Upload overview. Note The URLs must be URL-encoded. Separate multiple URLs with commas (,). You can specify up to 20 URLs. To prevent upload failures caused by special characters, URL-encode** the URLs before concatenating them with commas.	https://****.mp4
TemplateGroupId	string	No	The ID of the transcoding template group. You can obtain the ID by using one of the following methods: Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing Configuration > Transcoding Template Groups to view the ID of the transcoding template group. When you create a transcoding template group by calling the Create a transcoding template group operation, the ID of the transcoding template group is the value of the TranscodeTemplateGroupId response parameter. When you query transcoding template groups by calling the Query transcoding template groups operation, the ID is the value of the TranscodeTemplateGroupId response parameter. Note If you do not specify the ID of a transcoding template group, the default transcoding template group is used for transcoding. If you specify the ID of a transcoding template group, the specified template group is used for transcoding. You can also set this parameter in `UploadMetadatas`. If TemplateGroupId is set in both `UploadMetadatas` and here, the TemplateGroupId set in `UploadMetadatas` prevails.	ca3a8f6e4957b65806709586****
StorageLocation	string	No	The storage address of the media file. Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Asset Management Configuration > Storage Management to view the storage address. If you do not specify this parameter, the default storage address is used.	outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
UploadMetadatas	string	No	The metadata of the media files to be uploaded. The value is a JSON string. The metadata takes effect only when it matches the URL in UploadURLs. JSON format: `[UploadMetadata, UploadMetadata,…]`. The value must be converted to a JSON string. For more information, see the UploadMetadata table below.	[{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
UserData	string	No	The custom settings. The value is a JSON string. You can configure settings such as message callbacks and upload acceleration. For more information, see UserData. Note To use the message callback feature 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. 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 apply for activation. For more information, see Upload instructions. For more information about 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. Default value: app-1000000. For more information, see Multi-application.	app-****
WorkflowId	string	No	The workflow ID. You can log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing Configuration > Workflow Management to view the workflow ID. Note If both WorkflowId and TemplateGroupId are passed, WorkflowId prevails. For usage instructions, see Workflows.	e1e243b42548248197d6f74f9****
SessionId	string	No	The custom deduplication identifier. If this parameter is passed in a request and a request with the same identifier was detected within the past 10 minutes, an error is returned for the current request. Note The deduplication identifier is custom. It can be up to 50 characters in length and supports uppercase and lowercase letters, digits, hyphens (-), and underscores (_). If you do not pass this parameter or pass an empty string, deduplication is not performed.	5c62d40299034bbaa4c195da330****
EnableFirstFrameCover	boolean	No	Specifies whether to use the first frame of the video as the cover.
GenerateThumbnail	boolean	No	Specifies whether to generate a thumbnail for the video.

UploadMetadata

Name	Type	Required	Description
SourceURL	String	Yes	The URL of the source media file to be uploaded.
Title	String	No	The media title. The value can be up to 128 bytes in length and must be encoded in UTF-8.
FileSize	String	No	The file size.
Description	String	No	The description. The value can be up to 1,024 bytes in length and must be encoded in UTF-8.
CoverURL	String	No	The custom URL of the video cover.
CateId	String	No	The category ID. You can log on to the ApsaraVideo VOD console and choose Configuration Management > Media Asset Management Configuration > Category Management to view the category ID.
Tags	String	No	The tags. A single tag can be up to 32 bytes in length. You can specify up to 16 tags. Separate multiple tags with commas (,). Encode the value in UTF-8.
TemplateGroupId	String	No	The ID of the transcoding template group. This value overrides the TemplateGroupId passed at the outer level.
WorkflowId	String	No	The workflow ID. If both WorkflowId and TemplateGroupId are passed, WorkflowId prevails. For more information, see Workflows.
FileExtension	String	No	The file name extension of the media file. For supported file name extensions, see Upload overview.
ReferenceId	String	No	The custom ID. The value can be 6 to 64 characters in length and supports only lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be unique per user.

Note

Parameters in UploadMetadata (such as Title, Description, and Tags) cannot contain emojis.
To ensure normal playback, if you set TemplateGroupId to "VOD_NO_TRANSCODE" to upload video files without transcoding, only files in the following formats support direct playback without transcoding: MP4, FLV, MP3, M3U8, and WEBM. Files in other formats are only stored (pay attention to the file name extension of FileName). If you use the Alibaba Cloud player, the version must be 3.1.0 or later.
If you specify a template group that does not transcode (TemplateGroupId is set to "VOD_NO_TRANSCODE"), only the Video upload complete event notification is generated after the video is uploaded. The Single-definition transcoding complete event notification is not generated.
If a callback is configured, after the video is uploaded, you will receive the URL-based video upload complete event notification in addition to the upload and transcoding notifications.
When you submit tasks in batches, each SourceURL has an independent notification.

Response elements

Element	Type	Description	Example
	object	The response.
RequestId	string	The request ID.	25818875-5F78-4AF6-D7393642CA58****
UploadJobs	array<object>	The list of upload jobs.
	object	The details of the upload job.
SourceURL	string	The source file URL corresponding to 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.