Upload files using the Python SDK

This topic provides detailed examples of how to use the server-side upload SDK for Python to upload various media files to ApsaraVideo VOD.

Overview

The Python upload SDK follows the general process of the ApsaraVideo VOD server-side SDK. For more information, see Upload process. The basic process of using the Python upload SDK is as follows:

Complete the prerequisites. For more information, see Prerequisites.
Integrate the Python upload SDK. For more information, see Integrate the Python upload SDK.
Implement the upload logic. This step involves configuring upload information.
- For audio and video uploads, see Scenario 1: Upload audio and video files.
- For image uploads, see Scenario 2: Upload images.
- For auxiliary media asset uploads, see Scenario 3: Upload auxiliary media assets.
The default endpoint for the Python upload SDK is cn-shanghai (Shanghai). To upload media files to other regions, you can specify the region using ApiRegion in AliyunVodUploader.py. For more information about the endpoints that ApsaraVideo VOD supports, see Endpoints.

The following example shows how to set the upload region to cn-beijing (Beijing):
```
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 a RAM user and grant permissions.
Configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables. For more information, see Configure environment variables in Linux, macOS, and Windows.
Important
- An Alibaba Cloud account AccessKey pair has permissions on all API operations. Use a RAM user's AccessKey pair to call API operations or perform routine O&M.
- Do not hard-code your AccessKey ID and AccessKey secret in project code. If leaked, all resources in your account are compromised.
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 Obtain an STS token.

Integrate the Python upload SDK

Note

For a detailed description of the upload SDK directories, see Directory structure.
This topic uses a regular user as an example to describe the operations.

Run the following commands to install dependency packages.

sudo pip install aliyun-python-sdk-core

sudo pip install aliyun-python-sdk-vod

sudo pip install oss2

Note
If you use Python 3, change sudo pip install aliyun-python-sdk-core to sudo pip install aliyun-python-sdk-core-v3. If you have multiple Python versions installed, you can use the `pip3` command. If you encounter integration issues, see FAQ to troubleshoot the issues.
Download the Python upload SDK and sample code.
- SDK version: 1.3.2.2
- Update time: 2022-02-24
- Download address: V1.3.2.2 SDK and demo source code
Decompress VodUploadSDK-Python_1.3.*.zip and copy the voduploadsdk folder from the VodUploadSDK-Python_1.3.* directory to your local project directory (recommended) or the site-packages directory.

Update the Python upload SDK

If you find that new APIs or new features of existing APIs are not available in your current SDK, update the SDK to the latest version.

Run the following commands to update the dependency packages.

sudo pip install --upgrade aliyun-python-sdk-vod

sudo pip install --upgrade oss2
Download the latest Python upload SDK and overwrite the local SDK files. For more information, see SDK download.

Note
You can open the ChangeLog.txt file in the voduploadsdk directory to view the current SDK version number and release date.

Python upload SDK directory structure

The voduploadsdk directory

AliyunVodUtils.py

Directory	Description
AliyunVodLog	The log class of the upload SDK. It is implemented based on logging.
AliyunVodUtils	The utility class of the upload SDK.
AliyunVodException	The exception class of the upload SDK. It provides unified exception handling. You can catch this exception externally.

UploadVideoRequest.py

Directory

Description

UploadVideoRequest

The request class for uploading videos. For more information about the fields, see CreateUploadVideo.
UploadImageRequest.py

Directory

Description

UploadImageRequest

The request class for uploading images. For more information about the fields, see CreateUploadImage.
UploadAttachedMediaRequest.py

Directory

Description

UploadAttachedMediaRequest

The request class for uploading auxiliary media assets. For more information about the fields, see CreateUploadAttachedMedia.

AliyunVodUploader.py

Directory	Description
uploadLocalVideo	The API for uploading local videos.
uploadWebVideo	The API for uploading web videos.
uploadLocalM3u8	Uploads local M3U8 videos.
uploadWebM3u8	Uploads web M3U8 videos.
uploadImage	Uploads local or web image files.
uploadAttachedMedia	Uploads local or web auxiliary media asset files.
parseWebM3u8	Parses the shard information of a web M3U8 file.
parseLocalM3u8	Parses the shard information of a local M3U8 file.
setApiRegion	Sets the endpoint for VOD. The default value is cn-shanghai (Shanghai). Regions outside China, such as ap-southeast-1 (Singapore), are also supported. For more information, see VOD region IDs.
setMultipartUpload	Sets the threshold and part size for multipart upload.
uploadProgressCallback	The callback function for upload progress. You can rewrite this function.
setEnableCrc	Specifies whether to enable cyclic redundancy check (CRC) during upload. It is enabled by default.

ChangeLog.txt: Contains the release history. The first line indicates the current SDK version number and release date.

The samples directory

uploadVideo.py: Sample code for uploading videos.
uploadImage.py: Sample code for uploading images.
uploadAttachedMedia.py: Sample code for uploading auxiliary media asset files.

Scenario 1: Upload audio and video files

Upload regular files

You can upload the following types of audio and video files:

Local files: Multipart upload is used. The maximum size of a single file is 48.8 TB. Resumable upload is not supported. For more information, see the `testUploadLocalVideo` function in the sample code.
Web files: You can specify a file URL for the upload. The maximum size of a single file is 48.8 TB. This method requires downloading the web file to a local disk before uploading. Make sure that your local disk has sufficient space. For more information, see the `testUploadWebVideo` function in the sample code.

Click to view the sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadVideoRequest import UploadVideoRequest 
# Test uploading a local audio or video file
def testUploadLocalVideo(accessKeyId, accessKeySecret, filePath, storageLocation=None):
    try:
        # You can specify the region where the upload script is deployed. If the ECS region is the same as the ApsaraVideo VOD storage region, the upload is automatically performed over the internal network. This is faster and saves 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')
        # You can set a video thumbnail. If it is a local or web image, you can use UploadImageRequest to upload the image to ApsaraVideo VOD and obtain the ImageURL.
        # ImageURL example: https://example.com/sample-****.jpg
        #uploadVideoRequest.setCoverURL('<your Image URL>')  
        # 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 uploading a web 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 of an Alibaba Cloud account has permissions on all APIs. We recommend that you use the AccessKey of a RAM user for API calls or routine O&M.
# Do not store your AccessKey ID and AccessKey secret in your project code. This can lead to a leak of your AccessKey and compromise the security of all resources under your account.
# This example reads the AccessKey from environment variables for identity verification. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
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)
# fileURL example: http://video.developer.aliyundoc.com/video/sample-****.mp4
fileUrl = '<your file URL>'
#testUploadWebVideo(accessKeyId, accessKeySecret, fileUrl)

Upload M3U8 files

Click to view the sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadVideoRequest import UploadVideoRequest
# Test uploading a local M3U8 video
def testUploadLocalM3u8(accessKeyId, accessKeySecret, m3u8LocalFile):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8LocalFile, 'exampleTitle')
        # uploadVideoRequest.setTemplateGroupId('<TemplateGroupId>')
        # The segment files and the M3U8 file are in the same directory. The SDK automatically parses and uploads them.
        videoId = uploader.uploadLocalM3u8(uploadVideoRequest)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))
    except AliyunVodException as e:
        print(e)
# Test uploading a web M3U8 video
def testUploadWebM3u8(accessKeyId, accessKeySecret, m3u8FileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8FileUrl, 'exampleTitle')
        # Parse the segment file URLs. This applies when the segment URLs have the same signature as the M3U8 file or have no signature. In other cases, you need to parse them yourself.
        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 of an Alibaba Cloud account has permissions on all APIs. We recommend that you use the AccessKey of a RAM user for API calls or routine O&M.
# Do not store your AccessKey ID and AccessKey secret in your project code. This can lead to a leak of your AccessKey and compromise the security of all resources under your account.
# This example reads the AccessKey from environment variables for identity verification. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
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)

Upload acceleration

To upload large files (at the GB or TB level) or perform cross-region uploads, such as uploading a video from the Chinese mainland to a storage address in the Singapore storage region, you can enable the upload acceleration feature. For more information, see Enable upload acceleration. After you enable this feature, you must add the AccelerateConfig key-value pair to the UserData object in the upload configuration. If the `UserData` object does not exist, you must create it. The following is an example:

uploadVideoRequest.setUserData("{\"AccelerateConfig\":{\"Type\":\"oss\",\"Domain\":\"****Bucket.oss-accelerate.aliyuncs.com\"}}");

Parameter description

Name	Type	Description
Type	string	The type of upload acceleration to enable. Only `oss` is supported.
Domain	string	The accelerated domain name of your bucket. The default protocol is HTTPS. Note Use an accelerated domain name assigned after activation, for example, `vod-*******.oss-accelerate.aliyuncs.com`.

Scenario 2: Upload images

Click to view the sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadImageRequest import UploadImageRequest
# Test uploading a local image
def testUploadLocalImage(accessKeyId, accessKeySecret, filePath):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(filePath)
        uploadImageRequest.setTitle('exampleTitle')  # Set the image title. The default value is 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 uploading a web image
def testUploadWebImage(accessKeyId, accessKeySecret, fileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(fileUrl)
        uploadImageRequest.setTitle('exampleTitle')  # Set the image title. The default value is 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 of an Alibaba Cloud account has permissions on all APIs. We recommend that you use the AccessKey of a RAM user for API calls or routine O&M.
# Do not store your AccessKey ID and AccessKey secret in your project code. This can lead to a leak of your AccessKey and compromise the security of all resources under your account.
# This example reads the AccessKey from environment variables for identity verification. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
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

Click to view the sample code

# -*- coding: UTF-8 -*-
from voduploadsdk.AliyunVodUtils import *
from voduploadsdk.AliyunVodUploader import AliyunVodUploader
from voduploadsdk.UploadAttachedMediaRequest import UploadAttachedMediaRequest
# Test uploading a local auxiliary media asset (such as a watermark or caption 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 uploading a web auxiliary media asset (such as a watermark or caption 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 of an Alibaba Cloud account has permissions on all APIs. We recommend that you use the AccessKey of a RAM user for API calls or routine O&M.
# Do not store your AccessKey ID and AccessKey secret in your project code. This can lead to a leak of your AccessKey and compromise the security of all resources under your account.
# This example reads the AccessKey from environment variables for identity verification. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
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

When you use the sample code to upload a web video stream, if the ERROR:root:Download fail: [Errno 2] No such file or directory error is reported, you can resolve the issue by manually creating a dlfiles folder in the same directory as the voduploadsdk folder.

/Users/fulin/Documents/Code/PythonProject/VodPythonUploadSdkTest/venv/bin/python  /Users/fulin/Documents/Code/PythonProject/VodPythonUploadSdkTest/uploadVideo.py
[2022-02-16 20:54:59]Download https://img.a...                              To /Users/fulin/Documents/Code/PythonProject/
/Users/fulin...                                                              : InsecureRequestWarning: Unverifi...
    warnings.warn(...)
[2022-02-16 20:54:59]Download fail: [Errno 2] No such file or directory: '/Users/fulin/Documents/Code/PythonProject/VodPythonUploadSdkTest/dlfiles/115...
Type: FileDownloadError, Code: Download File Error, Message: , HTTPStatus: NULL, RequestId: NULL
ERROR:root:Download fail: [Errno 2] No such file or directory: '/Users/fulin/Documents/Code/PythonProject/VodPythonUploadSdkTest/dlfiles/115310cd4d...
Process finished with exit code 0

Directory	Description
UploadVideoRequest	The request class for uploading videos. For more information about the fields, see CreateUploadVideo.

Directory	Description
UploadImageRequest	The request class for uploading images. For more information about the fields, see CreateUploadImage.

Directory	Description
UploadAttachedMediaRequest	The request class for uploading auxiliary media assets. For more information about the fields, see CreateUploadAttachedMedia.