全部產品
Search

搜尋本產品

    ApsaraVideo VOD：使用Python SDK上傳檔案

    文件中心

    ApsaraVideo VOD：使用Python SDK上傳檔案

    更新時間：May 27, 2025

    本文通過樣本詳細介紹如何使用服務端上傳SDK（Python語言）將各類媒體檔案上傳至點播儲存。

    整體說明

    從內部邏輯角度看，Python上傳SDK遵循點播服務端SDK的通用流程。詳情請參見上傳流程。從操作角度看，使用Python上傳SDK的基礎流程如下：

    1. 完成前提條件。具體操作請參見前提條件。

    2. 整合Python上傳SDK。具體操作請參見整合Python上傳SDK。

    3. 實現上傳邏輯（主要是上傳資訊配置）。

    4. Python上傳SDK預設服務存取點為cn-shanghai（上海）, 若需要上傳媒體檔案到其他地區，可以通過AliyunVodUploader.py中的ApiRegion來指定地區，點播支援的服務存取點，請參見服務存取點。

      以指定上傳地區為cn-beijing（北京）為例，配置樣本如下：

      self.setApiRegion('cn-beijing')

    前提條件

    • 您已經開通了ApsaraVideo for VOD服務。開通步驟請參見開通ApsaraVideo for VOD服務。

    • 您已經完成上傳相關的系統配置，包括啟用目標儲存地區的儲存地址和配置回調。操作指引請參見管理儲存Bucket及回調設定。

    • 您已準備好用於調用點播服務的帳號。為避免阿里雲帳號AccessKey泄露帶來的安全風險，推薦您建立RAM使用者並授予其VOD相關許可權。然後使用RAM使用者的AK對（AccessKey ID和AccessKey Secret）訪問點播服務。操作指引請參見建立RAM使用者並授權。

    • 已配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。具體操作，請參見在Linux、macOS和Windows系統配置環境變數。

      重要

      • 阿里雲帳號的AccessKey擁有所有API的存取權限，建議您使用RAM使用者的AccessKey進行API訪問或日常營運。

      • 強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。

    • （可選）如需使用STS臨時授權方式（阿里雲Security Token Service）訪問點播服務，請為RAM使用者建立角色並授予角色VOD相關許可權。操作指引請參見擷取STS Token。

    整合Python上傳SDK

    說明

    • 上傳SDK目錄詳細介紹請參見下文目錄說明。

    • 本文以普通使用者執行操作為例進行說明。

    1. 執行以下命令安裝依賴包。

      sudo pip install aliyun-python-sdk-core

      sudo pip install aliyun-python-sdk-vod

      sudo pip install oss2

      說明

      如果使用的是 Python 3.x，請將sudo pip install aliyun-python-sdk-core修改為sudo pip install aliyun-python-sdk-core-v3。如果同時安裝了不同版本，可使用pip3命令。如果整合遇到問題，請參見常見問題排查。

    2. 下載Python上傳SDK及範例程式碼VodUploadSDK-Python_1.3.*.zip。

    3. 解壓VodUploadSDK-Python_1.3.*.zip，將VodUploadSDK-Python_1.3.*目錄下的voduploadsdk複製到本地專案工程目錄下（推薦），或複製到site-packages目錄下。

    更新Python上傳SDK

    若發現新的介面或已有介面新的功能在當前SDK沒有，可將SDK更新到最新版。

    1. 執行以下命令更新依賴包。

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

      sudo pip install --upgrade oss2

    2. 下載最新的Python上傳SDK覆蓋到本地SDK檔案。更多資訊，請參見SDK下載。

      說明

      您可以開啟voduploadsdk目錄下的ChangeLog.txt檔案查看當前SDK的版本號碼和發布日期。

    Python上傳SDK目錄說明

    voduploadsdk目錄

    • AliyunVodUtils.py

      目錄

      說明

      AliyunVodLog

      上傳SDK的日誌類，基於logging實現。

      AliyunVodUtils

      上傳SDK的工具類。

      AliyunVodException

      上傳SDK的異常類，做統一的異常處理，外部捕獲此異常即可。

    • UploadVideoRequest.py

      目錄

      說明

      UploadVideoRequest

      上傳視頻的請求類，欄位請參見擷取音視頻上傳地址和憑證。

    • UploadImageRequest.py

      目錄

      說明

      UploadImageRequest

      上傳圖片的請求類，欄位請參見擷取圖片上傳地址和憑證。

    • UploadAttachedMediaRequest.py

      目錄

      說明

      UploadAttachedMediaRequest

      上傳輔助媒資的請求類，欄位請參見擷取輔助媒資上傳地址和憑證。

    • AliyunVodUploader.py

      目錄

      說明

      uploadLocalVideo

      上傳本地視頻的介面。

      uploadWebVideo

      上傳網路視頻的介面。

      uploadLocalM3u8

      上傳本地m3u8視頻。

      uploadWebM3u8

      上傳網路m3u8視頻。

      uploadImage

      上傳本地或網狀圖片檔案。

      uploadAttachedMedia

      上傳本地或網路輔助媒資檔案。

      parseWebM3u8

      解析網路m3u8檔案的分區資訊。

      parseLocalM3u8

      解析本地m3u8檔案的分區資訊。

      setApiRegion

      設定VoD的接入地址。預設為cn-shanghai（上海），海外支援ap-southeast-1（新加坡）等地區。詳情請參見點播地區標識。

      setMultipartUpload

      設定分區上傳的閾值、分區大小。

      uploadProgressCallback

      上傳進度回呼函數，可重寫。

      setEnableCrc

      上傳時是否啟用CRC校正，預設開啟。

    • ChangeLog.txt：版本發布記錄，首行即為當前SDK的版本號碼和發布日期。

    samples目錄

    • uploadVideo.py：上傳視頻的範例程式碼。

    • uploadImage.py：上傳圖片的範例程式碼。

    • uploadAttachedMedia.py：上傳輔助媒資檔案的範例程式碼。

    情境一：上傳音視頻

    普通檔案上傳

    音視頻上傳目前支援以下類型檔案上傳：

    • 上傳本地檔案，使用分區上傳，最大支援48.8 TB的單個檔案，不支援斷點續傳。請參見範例程式碼中的testUploadLocalVideo函數。

    • 上傳網路檔案，可指定檔案URL進行上傳，最大支援48.8 TB的單個檔案。該上傳方式需要先將網路檔案下載到本地磁碟，再進行上傳，所以要保證本地磁碟有充足的空間。請參見testUploadWebVideo函數。

    展開查看範例程式碼

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

# 測試上傳本地音視頻
def testUploadLocalVideo(accessKeyId, accessKeySecret, filePath, storageLocation=None):
    try:
        # 可以指定上傳指令碼部署的ECS地區。如果ECS地區和ApsaraVideo for VOD儲存地區相同，則自動使用內網上傳，上傳更快且更省公網流量。
        # ecsRegionId ="cn-shanghai"
        # uploader = AliyunVodUploader(accessKeyId, accessKeySecret, ecsRegionId)
        # 不指定上傳指令碼部署的ECS地區。
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(filePath, 'exampleTitle')
        # 可以設定視頻封面，如果是本地或網狀圖片可使用UploadImageRequest上傳圖片到ApsaraVideo for VOD，擷取到ImageURL
        #ImageURL樣本：https://example.com/sample-****.jpg
        #uploadVideoRequest.setCoverURL('<your Image URL>')  
        # 標籤
        #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)
 
# 測試上傳網路音視頻
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)

####  執行測試代碼   ####   
# 阿里雲帳號AccessKey擁有所有API的存取權限，建議您使用RAM使用者進行API訪問或日常營運。
# 強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。
# 本樣本通過從環境變數中讀取AccessKey，來實現API訪問的身分識別驗證。運行程式碼範例前，請配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和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)

# fileURL樣本：http://video.developer.aliyundoc.com/video/sample-****.mp4
fileUrl = '<your file URL>'
#testUploadWebVideo(accessKeyId, accessKeySecret, fileUrl)

    M3U8檔案上傳

    展開查看範例程式碼

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

# 測試上傳m3u8本地視頻
def testUploadLocalM3u8(accessKeyId, accessKeySecret, m3u8LocalFile):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8LocalFile, 'exampleTitle')
        # uploadVideoRequest.setTemplateGroupId('<TemplateGroupId>')
        # 分區檔案和m3u8檔案位於同一目錄，SDK會自動解析上傳
        videoId = uploader.uploadLocalM3u8(uploadVideoRequest)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))

    except AliyunVodException as e:
        print(e)

# 測試上傳m3u8網路視頻
def testUploadWebM3u8(accessKeyId, accessKeySecret, m3u8FileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadVideoRequest = UploadVideoRequest(m3u8FileUrl, 'exampleTitle')
        # 解析分區檔案地址（適用於分區地址和m3u8檔案簽名相同或無簽名的情況，其他情況需要您自行解析）
        sliceFileUrls = uploader.parseWebM3u8(m3u8FileUrl)
        videoId = uploader.uploadWebM3u8(uploadVideoRequest, sliceFileUrls)
        print("file: %s, videoId: %s" % (uploadVideoRequest.filePath, videoId))

    except AliyunVodException as e:
        print(e)

####  執行測試代碼   ####
# 阿里雲帳號AccessKey擁有所有API的存取權限，建議您使用RAM使用者進行API訪問或日常營運。
# 強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。
# 本樣本通過從環境變數中讀取AccessKey，來實現API訪問的身分識別驗證。運行程式碼範例前，請配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和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)

    上傳加速

    當您需要上傳較大檔案（GB、TB層級）或進行跨地區上傳（比如在中國內地將視頻上傳到新加坡儲存地區的儲存地址）時，您可以啟用上傳加速功能。詳情請參見開通方式。開通後需要您在上傳配置中的UserData對象（若沒有需要建立）增加相應的key-value值AccelerateConfig。樣本如下：

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

    參數描述

    名稱

    類型

    說明

    Type

    string

    開啟上傳加速的類型（僅支援oss）。

    Domain

    string

    使用者bucket的加速地址（預設為https）。

    說明

    使用開通後分配的一個加速地址，例如：vod-*******.oss-accelerate.aliyuncs.com。

    情境二：上傳圖片

    展開查看範例程式碼

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

# 測試上傳本地圖片
def testUploadLocalImage(accessKeyId, accessKeySecret, filePath):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(filePath)
        uploadImageRequest.setTitle('exampleTitle')  # 設定圖片標題，預設為空白
        imageId, imageUrl = uploader.uploadImage(uploadImageRequest, True)
        print("file: %s, imageId: %s, imageUrl: %s" % (uploadImageRequest.filePath, imageId, imageUrl))

    except AliyunVodException as e:
        print(e)

# 測試上傳網狀圖片
def testUploadWebImage(accessKeyId, accessKeySecret, fileUrl):
    try:
        uploader = AliyunVodUploader(accessKeyId, accessKeySecret)
        uploadImageRequest = UploadImageRequest(fileUrl)
        uploadImageRequest.setTitle('exampleTitle')  # 設定圖片標題，預設為空白
        imageId, imageUrl = uploader.uploadImage(uploadImageRequest, False)
        print("file: %s, imageId: %s, imageUrl: %s" % (uploadImageRequest.filePath, imageId, imageUrl))

    except AliyunVodException as e:
        print(e)


####  執行測試代碼   ####
# 阿里雲帳號AccessKey擁有所有API的存取權限，建議您使用RAM使用者進行API訪問或日常營運。
# 強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。
# 本樣本通過從環境變數中讀取AccessKey，來實現API訪問的身分識別驗證。運行程式碼範例前，請配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和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)

    情境三：上傳輔助媒資

    展開查看範例程式碼

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


# 測試上傳本地輔助媒資(浮水印、字幕等檔案)
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)


# 測試上傳網路輔助媒資(浮水印、字幕等檔案)
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)


####  執行測試代碼   ####
# 阿里雲帳號AccessKey擁有所有API的存取權限，建議您使用RAM使用者進行API訪問或日常營運。
# 強烈建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。
# 本樣本通過從環境變數中讀取AccessKey，來實現API訪問的身分識別驗證。運行程式碼範例前，請配置環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和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)

    常見問題

    使用範例程式碼上傳網路視頻流時，如果報ERROR:root:Download fail: [Errno 2] No such file or directory錯誤，解決辦法為：在voduploadsdk同級目錄下手動建立dlfiles檔案夾。錯誤