All Products
Search
Document Center

UploadMediaByURL

Last Updated: Jul 28, 2020

Description

You can call this operation to upload multiple media files based on the mezzanine file URLs. After an upload job is completed, you can receive an UploadByURLComplete event notification. You can call the GetURLUploadInfos operation to query the upload status.

Note: This operation returns the submission result of an upload job. The upload job is queued in the background and runs asynchronously. After the upload job is completed, a callback message is sent, indicating whether the upload job succeeds or fails.

Request parameters

NameTypeRequiredDescription
ActionStringYesThe operation that you want to perform. Set this parameter to UploadMediaByURL.
UploadURLs StringYesThe URLs of the video mezzanine files.
  • The extension must be included in each URL. For example, in https://xxxx.mp4, mp4 is the extension. For more information about the extensions supported by ApsaraVideo for VOD, see Restrictions in Upload overview.
  • Separate multiple URLs with commas (,). You can enter a maximum of 100 URLs.
  • A video cannot be uploaded if its URL contains a special character. To resolve this issue, encode each video URL before concatenating them with commas (,).
TemplateGroupIdStringNoThe ID of the transcoding template group.
  • To view the template group ID, log on to the ApsaraVideo for VOD console and choose Global Settings > Transcode in the left-side navigation pane.
  • If you set this parameter, the system uses the specified template group to transcode videos.
  • You can also set this parameter in the UploadMetadatas parameter.
StorageLocationStringNoThe bucket for storing videos.
UploadMetadatasUploadMetadata NoThe metadata of the uploaded video. The value is a JSON-formatted string.
  • This parameter takes effect only when its value matches a URL specified by the UploadURLs parameter.
  • The data in JSON format, such as UploadMetadata, must be converted to a JSON-formatted string.
  • For more information, see the parameter description of UploadMetadata.
UserDataUserDataNoThe custom configurations. The value is a JSON-formatted string. The configurations include the callback configuration for event notifications.

UploadMetadata

NameTypeRequiredDescription
SourceURL StringYesThe URL of the video mezzanine file to be uploaded.
Title StringYesThe title of the video.
  • Length constraint: Maximum length of 128 bytes.
  • Encoding: UTF-8.
FileSize StringNoThe size of the video mezzanine file.
Description StringNoThe description of the video.
  • Length constraint: Maximum length of 1,024 bytes.
  • Encoding: UTF-8.
CoverURL StringNoThe URL of the custom video thumbnail.
CateId StringNoThe ID of the video category.To view or edit the category ID, log on to the ApsaraVideo for VOD console and choose Global Settings > Categories in the left-side navigation pane.
Tags StringNoThe tag of the video.
  • Length constraint per tag: Maximum length of 32 bytes. You can enter a maximum of 16 tags.
  • Separate multiple tags with commas (,).
  • Encoding: UTF-8.
TemplateGroupIdStringNoThe ID of the transcoding template group.
  • To view the template group ID, log on to the ApsaraVideo for VOD console and choose Global Settings > Transcode in the left-side navigation pane.
  • If you set this parameter, the system uses the specified template group to transcode videos.
  • The value of this parameter overwrites that of the TemplateGroupId parameter specified for the UploadMediaByURL operation.

Note:

  • Parameters (such as Title, Description, and Tags) in the UploadMetadata structure cannot contain emoticons.
  • To ensure normal playback, the Distribution Without Transcoding template group is available only to videos in .mp4, .flv, and .m3u8 formats. If ApsaraVideo Player is used, its version must be 3.1.0 or later.
  • If you select the No Transcoding template group, ApsaraVideo for VOD sends a FileUploadComplete event notification after an upload job is completed, but without a StreamTranscodeComplete event notification.
  • In addition to the FileUploadComplete and StreamTranscodeComplete event notifications, ApsaraVideo for VOD sends an UploadByURLComplete event notification after an upload job is completed.
  • If you specify multiple URLs, ApsaraVideo for VOD sends event notifications separately for each URL specified by the SourceURL parameter.

Response parameters

NameTypeDescription
RequestIdStringThe ID of the request.
UploadJobUploadJob The information about multiple jobs. For more information, see the parameter description of UploadJob.

UploadJob

NameTypeDescription
JobIdStringThe ID of the upload job.
SourceURLStringThe URL of the video mezzanine file uploaded in the upload job.

Note: This operation uploads videos asynchronously. Upload jobs need to be queued for execution after they are submitted. The completion time of each upload job depends on the number of jobs in the queue.

API examples

Sample request

  1. http://vod.cn-shanghai.aliyuncs.com/?Action=CreateUploadVideo&Action=UploadVideoByURL&sourceURLs=http://xxxx&UploadMetadatas =[xxxx]&Format=JSON&<Common request parameters>

Note: For more information about common request parameters, see Common parameters.

Sample response

JSON format

  1. {
  2. "RequestId": "25818875-5F78-4A13-BEF6-D7393642CA58",
  3. "UploadJobs": [{
  4. "JobId": "ad90a501b1b94ba6afb72374ad005046",
  5. "SourceURL":"http://xxxxxx.mp4"
  6. },
  7. ...
  8. ]
  9. }

Error codes

This operation also returns common errors. For more information about errors common to all operations, see common errors.

Error codeError messageHTTP status codeDescription
InvalidParameter.UploadURLsThe specified parameter UploadURLs is not valid.400The error message returned because the specified UploadURLs parameter is invalid.

SDK examples

We recommend that you use a server SDK to call this operation. For more information about the sample code used to call this operation in various languages, see the following topics: