UploadMediaByURL-阿里云帮助中心

Operation description

Description

If a callback is configured, the service sends an event notification when the URL upload is complete. You can query the upload status by calling the API to retrieve URL upload information.
After you successfully submit an upload job, the system creates an asynchronous task in the cloud and queues it for execution. After the upload is complete, you can use the URL and media ID from the event notification (message callback) to update your records.

Limitations

This API supports uploading files to VOD storage only and does not support uploading to your own Object Storage Service (OSS) buckets. To use your own OSS storage, you must first pull the files to a local device, upload them to OSS by using the OSS SDK, and then call the RegisterMediaInfo API to register the OSS object with the media asset library.
This API is currently available only in the China (Shanghai), China (Beijing), and China (Shenzhen) regions.
This API supports uploading audio and video files only.

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

ice:UploadMediaByURL

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
UploadURLs	string	No	The source URL of the media file. The URL must include a file extension. For example, in `https://****.mp4`, mp4 is the file extension. If the URL does not include a file extension, you can specify it by using the `FileExtension` parameter in `MediaMetaData`. If a file extension is present in both the URL and the `FileExtension` parameter, the value of `FileExtension` takes precedence. The URLs must be URL-encoded. Separate multiple URLs with commas (,). You can specify up to 20 URLs. To prevent upload failures due to special characters, URL-encode each URL before concatenating them with commas.	https://diffurl.mp4
AppId	string	No	The application ID.	app-1000000
UserData	string	No	Custom settings, provided as a JSON string. This parameter supports configurations such as message callbacks.	{"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
UploadTargetConfig	string	No	The destination storage location. The only valid value for `StorageType` is `oss`. `StorageLocation` supports VOD storage only and does not support your own OSS buckets.	{"StorageType":"oss","StorageLocation":"outin-***.oss-cn-shanghai.aliyuncs.com"}
MediaMetaData	string	No	The metadata of the media file, provided as a JSON string. This metadata takes effect only when it matches a URL in `UploadURLs`. The value must be a JSON array in the `[UploadMetadata, UploadMetadata, ...]` format, passed as a JSON string. For more information, see the UploadMetadata table below.	[{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
PostProcessConfig	string	No	Specifies post-upload processing actions for media files of type `video` or `audio`. The only supported value for `ProcessType` is `Workflow`.	{"ProcessType": "Workflow","ProcessID":"b72a06c6beeb4dcdb898feef067b1***"}
EntityId	string	No	The entity ID. You can call the CreateEntity API to create an entity and define a custom dynamic metadata schema.	d67281da3c8743b8823ad12976187***

UploadMetadata

Parameter	Type	Required	Description
SourceURL	String	Yes	The source URL of the media file to upload.
Title	String	Yes	The title of the media file. Maximum length: 128 bytes. Must be UTF-8 encoded.
FileSize	String	No	The size of the file.
Description	String	No	The description of the media file. Maximum length: 1,024 bytes. Must be UTF-8 encoded.
CoverURL	String	No	The URL of the custom video cover.
CateId	String	No	The category ID.
Tags	String	No	The tags of the media file. You can specify up to 16 tags, each up to 32 bytes in length. Separate multiple tags with a comma (,). The tags must be UTF-8 encoded.
WorkflowId	String	No	The workflow ID.
FileExtension	String	No	The file extension of the media file.
DynamicMetaData	String	No	Dynamic metadata. Example: `{"Uploader": "xxx"}`.
EntityId	String	No	The entity ID.

Note

The WorkflowId parameter triggers an asynchronous task. After submission, the service queues the job for asynchronous execution, so it does not complete immediately.
Parameters in UploadMetadata, such as Title, Description, and Tags, cannot contain emojis.
li data-t-idx="277">

When you submit a batch of jobs, the service sends a separate notification for each SourceURL.
For batch submissions, each SourceURL receives a separate notification.

Response elements

Element	Type	Description	Example
	object	The returned result.
RequestId	string	The request ID.	**83B7-7F87-4792-BFE9-63CD2137**
UploadJobs	array<object>	An array of upload jobs.
	object	The upload job details.
JobId	string	The upload job ID.	20ce1e05dba64576b96e9683879f0***
SourceURL	string	The source URL corresponding to the upload job.	http://example****.mp4
MediaId	string	The media ID.	f476988629f54a7b8a4ba90d1a6c7***

Examples

Success response

JSON format

{
  "RequestId": "****83B7-7F87-4792-BFE9-63CD2137****",
  "UploadJobs": [
    {
      "JobId": "20ce1e05dba64576b96e9683879f0***",
      "SourceURL": "http://example****.mp4\n",
      "MediaId": "f476988629f54a7b8a4ba90d1a6c7***"
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.