Use the upload SDK for Python to upload files - ApsaraVideo VOD

This topic describes how to use the upload SDK for Python to upload media files to ApsaraVideo VOD.

Upload process

The upload SDK for Python follows the general upload process of ApsaraVideo VOD SDKs. For more information, see Upload process. The following content describes the basic process of using the server upload SDK for Python:

Complete the configurations as described in the Prerequisites section of this topic.
Integrate the upload SDK for Python. For more information, see Integrate the upload SDK for Python.
Configure upload information to implement the upload logic.
- For more information about how to upload audio or video files, see Scenario 1: Upload audio and video files.
- For more information about how to upload images, see Scenario 2: Upload images.
- For more information about how to upload auxiliary media assets, see Scenario 3: Upload auxiliary media assets.
Specify ApiRegion in AliyunVodUploader.py if you want to upload media files to a region other than the China (Shanghai) region. By default, the upload SDK for Python uploads media files to cn-shanghai. For more information about the supported endpoints, see Endpoints.
The following sample code provides an example on how to specify the China (Beijing) region:
```
self.setApiRegion('cn-beijing')
```

Prerequisites

ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.
The system settings required for the upload, including the storage path in the specified region and the callback settings, are configured. For more information, see Manage storage buckets and Configure callbacks.
A RAM user is created and used to access ApsaraVideo VOD. To prevent security risks caused by the leakage of the AccessKey pair of your Alibaba Cloud account, we recommend that you create a RAM user and grant the RAM user the permissions required to access ApsaraVideo VOD. Then, you can use the AccessKey pair of the RAM user to access ApsaraVideo VOD. For more information, see Create and grant permissions to a RAM user.
Optional. A role is created for the RAM user and the role is granted the permissions required to access ApsaraVideo VOD if you want to access ApsaraVideo VOD by using Security Token Service (STS). For more information, see Use STS to upload videos.
Note
For more information about the scenarios in which STS can be used, see Comparison between credentials and STS.

Integrate the upload SDK for Python

Note

For more information about the directories of the upload SDK for Python, see Directories.
The following section describes how to integrate the upload SDK for Python as a non-root user.

Run the following commands to install dependencies:
sudo pip install aliyun-python-sdk-core
sudo pip install aliyun-python-sdk-vod
sudo pip install oss2
Note
If you use Python 3.x, replace sudo pip install aliyun-python-sdk-core with sudo pip install aliyun-python-sdk-core-v3. If you have installed multiple versions of Python, you can run the pip3 command. If errors occur when you integrate the SDK, troubleshoot the errors by following the instructions provided in FAQ.
Download the VodUploadSDK-Python_1.3.*.zip package, which contains the upload SDK for Python and sample code. For more information, see Upload SDK.
Note
In this topic, the SDK V1.3.1 is used as an example. You can use other versions based on your business requirements.
Decompress the VodUploadSDK-Python_1.3.*.zip package and copy voduploadsdk from the VodUploadSDK-Python_1.3.* directory to the directory of your local project or the site-packages directory. We recommend that you copy voduploadsdk to the directory of your local project.

Update the upload SDK for Python

If new operations or new features of existing operations are unavailable in the current SDK, update the SDK to the latest version.

Run the following commands to install dependencies:
sudo pip install --upgrade aliyun-python-sdk-vod
sudo pip install --upgrade oss2
Download the latest version of the upload SDK for Python to overwrite the existing SDK. For more information, see SDK overview and download.
Note
You can obtain the version number and release date of the current SDK in the first line of the ChangeLog.txt file in the voduploadsdk directory.

Directories

voduploadsdk

AliyunVodUtils.py

Directory	Description
AliyunVodLog	The log class of the upload SDK. The class is implemented based on logging.
AliyunVodUtils	The utility class of the upload SDK.
AliyunVodException	The exception class of the upload SDK. Unified exception handling is supported. You need to only detect AliyunVodException exceptions for external calls.

UploadVideoRequest.py
Directory
Description
UploadVideoRequest
The request class for video upload. For more information about the parameters, see CreateUploadVideo.
UploadImageRequest.py
Directory
Description
UploadImageRequest
The request class for image upload. For more information about the parameters, see CreateUploadImage.
UploadAttachedMediaRequest.py
Directory
Description
UploadAttachedMediaRequest
The request class for the upload of auxiliary media assets. For more information about the parameters, see CreateUploadAttachedMedia.

AliyunVodUploader.py

Directory	Description
uploadLocalVideo	The API operation that is used to upload local videos.
uploadWebVideo	The API operation that is used to upload online videos.
uploadLocalM3u8	The API operation that is used to upload local M3U8 videos.
uploadWebM3u8	The API operation that is used to upload online M3U8 videos.
uploadImage	The API operation that is used to upload local or online images.
uploadAttachedMedia	The API operation that is used to upload local or online auxiliary media assets.
parseWebM3u8	The API operation that is used to parse information about the file parts of online M3U8 videos.
parseLocalM3u8	The API operation that is used to parse information about the file parts of local M3U8 videos.
setApiRegion	The API operation that is used to specify the access region of ApsaraVideo VOD. Default value: cn-shanghai. You can specify a region outside the Chinese mainland, such as ap-southeast-1 for Singapore. For more information, see Region IDs of ApsaraVideo VOD.
setMultipartUpload	The API operation that is used to set the threshold of multipart upload and part size.
uploadProgressCallback	The API operation that is used to set the callback for the upload progress. This results can be overridden.
setEnableCrc	The API operation that is used to specify whether to enable cyclic redundancy check (CRC) during the upload. By default, CRC is enabled.

ChangeLog.txt: The version history. You can obtain the version number and release date of the SDK from the first line.

samples directory

uploadVideo.py: sample code for video upload.
uploadImage.py: sample code for image upload.
uploadAttachedMedia.py: sample code for the upload of auxiliary media assets.

Scenario 1: Upload audio and video files

Regular audio and video files

ApsaraVideo VOD allows you to upload audio or video files by using one of the following methods:

Use multipart upload to upload a local file. You can upload a file of up to 48.8 TB in size. Resumable upload is not supported. For more information, see the testUploadLocalVideo function in the sample code.
Use the file URL to upload an online file. You can upload a file of up to 48.8 TB in size. Before you upload online files, you must download the files to a local disk. Make sure that the local disk has sufficient space. For more information, see the testUploadWebVideo function in the sample code.

Show sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadVideoRequest import UploadVideoRequest 

# Test the upload of a local audio or video file.
def testUploadLocalVideo(accessKeyId, accessKeySecret, filePath, storageLocation=None):
    try:
        # Specify the region of the Elastic Compute Service (ECS) instance where the upload script is deployed. If the ECS region is the same as the storage region of ApsaraVideo VOD, the local file is automatically uploaded over the internal network. This accelerates uploads and reduces Internet traffic. 
        # ecsRegionId ="cn-shanghai"
        # uploader = AliyunVodUploader(accessKeyId, accessKeySecret, ecsRegionId)
        # Do not specify the ECS region where the upload script is deployed. 
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(filePath, 'exampleTitle')
        # Specify the video thumbnail. If the video thumbnail is a local or an online image, you can call the UploadImageRequest operation to upload the image to ApsaraVideo VOD and obtain the value of the ImageURL parameter.
        # Sample value of the ImageURL parameter: https://example.com/sample-****.jpg.
        #uploadVideoRequest.setCoverURL('<your Image URL>')  
        # Configure tags.
        #uploadVideoRequest.setTags('tag1,tag2')
        if storageLocation:
            uploadVideoRequest.setStorageLocation(storageLocation)
        videoId = uploader.uploadLocalVideo(uploadVideoRequest)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))
        
    except AliyunVodException as e:
        print(e)
 
# Test the upload of an online audio or video file.
def testUploadWebVideo(accessKeyId, accessKeySecret, fileUrl, storageLocation=None):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(fileUrl, 'exampleTitle')
        uploadVideoRequest.setTags('tag1,tag2')
        if storageLocation:
            uploadVideoRequest.setStorageLocation(storageLocation)
        videoId = uploader.uploadWebVideo(uploadVideoRequest)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))
        
    except AliyunVodException as e:
        print(e)

####   Run the test code.   ####   
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
# We recommend that you do not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
# In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
accessKeyId = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
accessKeySecret = os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']

localFilePath = '/opt/video/sample-****.mp4'
testUploadLocalVideo(accessKeyId, accessKeySecret, localFilePath)

# Sample value of the fileUrl parameter: example:http://video.developer.aliyundoc.com/video/sample-****.mp4.
fileUrl = '<your file URL>'
#testUploadWebVideo(accessKeyId, accessKeySecret, fileUrl)

M3U8 files

Show sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadVideoRequest import UploadVideoRequest

# Test the upload of a local M3U8 video file.
def testUploadLocalM3u8(accessKeyId, accessKeySecret, m3u8LocalFile):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8LocalFile, 'exampleTitle')
        # uploadVideoRequest.setTemplateGroupId('<TemplateGroupId>')
        # If the M3U8 file and file parts are stored in the same directory, the upload SDK automatically parses and uploads the M3U8 file.
        videoId = uploader.uploadLocalM3u8(uploadVideoRequest)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))

    except AliyunVodException as e:
        print(e)

# Test the upload of an online M3U8 video.
def testUploadWebM3u8(accessKeyId, accessKeySecret, m3u8FileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8FileUrl, 'exampleTitle')
        # If the URLs of part files use the same signature as that of the M3U8 file or no signature is available, ApsaraVideo VOD automatically parses the URLs of file parts. In other scenarios, you need to manually parse the URLs of part files.
        sliceFileUrls = uploader.parseWebM3u8(m3u8FileUrl)
        videoId = uploader.uploadWebM3u8(uploadVideoRequest, sliceFileUrls)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))

    except AliyunVodException as e:
        print(e)

####   Run the test code.   ####
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
# We recommend that you do not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
# In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
accessKeyId = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
accessKeySecret = os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']

m3u8LocalFile = '/opt/video/m3u8/example_01.m3u8'
#testUploadLocalM3u8(accessKeyId, accessKeySecret, m3u8LocalFile)

m3u8FileUrl = 'http://sample.oss.aliyuncs.com/video/m3u8/example****.m3u8'
#testUploadWebM3u8(accessKeyId, accessKeySecret, m3u8FileUrl)

Scenario 2: Upload images

Show sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadImageRequest import UploadImageRequest

# Test the upload of a local image.
def testUploadLocalImage(accessKeyId, accessKeySecret, filePath):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(filePath)
        uploadImageRequest.setTitle('exampleTitle')  # Specify the image title. By default, this parameter is left empty.
        imageId, imageUrl = uploader.uploadImage(uploadImageRequest, True)
        print("file: %s, imageId: %s, imageUrl: %s" % (uploadImageRequest.filePath, imageId, imageUrl))

    except AliyunVodException as e:
        print(e)

# Test the upload of an online image.
def testUploadWebImage(accessKeyId, accessKeySecret, fileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(fileUrl)
        uploadImageRequest.setTitle('exampleTitle')  # Specify the image title. By default, this parameter is left empty.
        imageId, imageUrl = uploader.uploadImage(uploadImageRequest, False)
        print("file: %s, imageId: %s, imageUrl: %s" % (uploadImageRequest.filePath, imageId, imageUrl))

    except AliyunVodException as e:
        print(e)


####   Run the test code.   ####
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
# We recommend that you do not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
# In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
accessKeyId = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
accessKeySecret = os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']

localFilePath = '/opt/image/image01.png'
#testUploadLocalImage(accessKeyId, accessKeySecret, localFilePath)

fileUrl = 'http://vod-download.cn-shanghai.aliyuncs.com/retina/pic/20180208/496AE240-54AE-4CC8-8578-3EEC8F38****.gif'
testUploadWebImage(accessKeyId, accessKeySecret, fileUrl)

Scenario 3: Upload auxiliary media assets

Show sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadAttachedMediaRequest import UploadAttachedMediaRequest


# Test the upload of a local auxiliary media asset such as a watermark or subtitle file.
def testUploadLocalAttachedMedia(accessKeyId, accessKeySecret, filePath):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadAttachedRequest = UploadAttachedMediaRequest(filePath, 'watermark')
        uploadAttachedRequest.setTitle('exampleTitle')
        media = uploader.uploadAttachedMedia(uploadAttachedRequest, True)
        print(media)

    except AliyunVodException as e:
        print(e)


# Test the upload of an online auxiliary media asset such as a watermark or subtitle file.
def testUploadWebAttachedMedia(accessKeyId, accessKeySecret, fileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadAttachedRequest = UploadAttachedMediaRequest(fileUrl, 'watermark')
        uploadAttachedRequest.setTitle('exampletitle')
        media = uploader.uploadAttachedMedia(uploadAttachedRequest, False)
        print(media)

    except AliyunVodException as e:
        print(e)


####   Run the test code.   ####
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
# We recommend that you do not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
# In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
accessKeyId = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
accessKeySecret = os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']

localFilePath = '/opt/image/sample.png'
#testUploadLocalAttachedMedia(accessKeyId, accessKeySecret, localFilePath)

fileUrl = 'http://vod-download.cn-shanghai.aliyuncs.com/retina/pic/20180208/496AE240-54AE-4CC8-8578-3EEC8F38****.gif'
testUploadWebAttachedMedia(accessKeyId, accessKeySecret, fileUrl)

FAQ

If the ERROR:root:Download fail: [Errno 2] No such file or directory error message is returned when you use the sample code to upload an online video stream, you can create the dlfiles folder in the directory at the same level as voduploadsdk to fix the error.

References

Overview

STS SDK overview

Directory	Description
UploadVideoRequest	The request class for video upload. For more information about the parameters, see CreateUploadVideo.

Directory	Description
UploadImageRequest	The request class for image upload. For more information about the parameters, see CreateUploadImage.

Directory	Description
UploadAttachedMediaRequest	The request class for the upload of auxiliary media assets. For more information about the parameters, see CreateUploadAttachedMedia.