Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Upload files using the Python SDK

Última atualização: Sep 22, 2026

Este tópico fornece exemplos detalhados de como usar o SDK de upload no lado do servidor em Python para fazer upload de vários arquivos de mídia no ApsaraVideo VOD.

Visão geral

O SDK de upload para Python segue o processo geral do SDK no lado do servidor do ApsaraVideo VOD. Para mais informações, consulte Upload process. O processo básico de uso do SDK de upload para Python é o seguinte:

  1. Cumpra os pré-requisitos. Para mais informações, consulte Prerequisites.

  2. Integre o SDK de upload para Python. Para mais informações, consulte Integrate the Python upload SDK.

  3. Implemente a lógica de upload. Esta etapa envolve a configuração das informações de upload.

  4. O endpoint padrão do SDK de upload para Python é cn-shanghai (Shanghai). Para fazer upload de arquivos de mídia em outras regiões, especifique a região com ApiRegion em AliyunVodUploader.py. Para mais informações sobre os endpoints compatíveis com o ApsaraVideo VOD, consulte Endpoints.

    O exemplo a seguir mostra como definir a região de upload como cn-beijing (Beijing):

    self.setApiRegion('cn-beijing')

Pré-requisitos

  • O ApsaraVideo VOD está ativado. Para mais informações, consulte Activate ApsaraVideo VOD.

  • Configure as definições de sistema necessárias para o upload, incluindo o caminho de armazenamento na região especificada e as configurações de callback. Para mais informações, consulte Manage storage buckets e Configure callbacks.

  • Crie um usuário do RAM e use-o para acessar o ApsaraVideo VOD. Para evitar riscos de segurança causados pelo vazamento do par de AccessKey da sua conta Alibaba Cloud, recomendamos a criação de um usuário do RAM com as permissões necessárias para acessar o ApsaraVideo VOD. Em seguida, use o par de AccessKey desse usuário do RAM para o acesso. Para mais informações, consulte Create a RAM user and grant permissions.

  • Configure as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET. Para mais informações, consulte Configure environment variables on Linux, macOS, and Windows.

    Importante
    • O par de AccessKey de uma conta Alibaba Cloud tem permissões para todas as operações de API. Use o par de AccessKey de um usuário do RAM para chamar operações de API ou executar operações e manutenção (O&M) de rotina.

    • Não codifique seu AccessKey ID e AccessKey Secret diretamente no código do projeto. Se houver vazamento, todos os recursos da sua conta serão comprometidos.

  • Opcional. Crie uma função para o usuário do RAM e conceda a ela as permissões necessárias para acessar o ApsaraVideo VOD, caso queira usar o Security Token Service (STS) para esse acesso. Para mais informações, consulte Obtain an STS token.

Integrar o SDK de upload para Python

Nota
  • Para uma descrição detalhada dos diretórios do SDK de upload, consulte Directory structure.

  • Este tópico usa um usuário comum como exemplo para descrever as operações.

  1. Execute os seguintes comandos para instalar os pacotes de dependência.

    sudo pip install aliyun-python-sdk-core

    sudo pip install aliyun-python-sdk-vod

    sudo pip install oss2

    Nota

    Se usar o Python 3, altere sudo pip install aliyun-python-sdk-core para sudo pip install aliyun-python-sdk-core-v3. Se houver várias versões do Python instaladas, use o comando pip3. Se encontrar problemas de integração, consulte FAQ para solucioná-los.

  2. Baixe o SDK de upload para Python e o código de exemplo.

  3. Descompacte VodUploadSDK-Python_1.3.*.zip e copie a pasta voduploadsdk do diretório VodUploadSDK-Python_1.3.* para o diretório do seu projeto local (recomendado) ou para o diretório site-packages.

Atualizar o SDK de upload para Python

Se notar que novas APIs ou novos recursos de APIs existentes não estão disponíveis no seu SDK atual, atualize o SDK para a versão mais recente.

  1. Execute os seguintes comandos para atualizar os pacotes de dependência.

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

    sudo pip install --upgrade oss2

  2. Baixe o SDK de upload para Python mais recente e substitua os arquivos locais do SDK. Para mais informações, consulte SDK download.

    Nota

    Abra o arquivo ChangeLog.txt no diretório voduploadsdk para visualizar o número da versão atual do SDK e a data de lançamento.

Estrutura de diretórios do SDK de upload para Python

O diretório voduploadsdk

  • AliyunVodUtils.py

    Diretório

    Descrição

    AliyunVodLog

    A classe de log do SDK de upload, implementada com base no logging.

    AliyunVodUtils

    A classe utilitária do SDK de upload.

    AliyunVodException

    A classe de exceção do SDK de upload. Fornece tratamento unificado de exceções, que podem ser capturadas externamente.

  • UploadVideoRequest.py

    Diretório

    Descrição

    UploadVideoRequest

    A classe de solicitação para upload de vídeos. Para mais informações sobre os campos, consulte CreateUploadVideo.

  • UploadImageRequest.py

    Diretório

    Descrição

    UploadImageRequest

    A classe de solicitação para upload de imagens. Para mais informações sobre os campos, consulte CreateUploadImage.

  • UploadAttachedMediaRequest.py

    Diretório

    Descrição

    UploadAttachedMediaRequest

    A classe de solicitação para upload de ativos de mídia auxiliares. Para mais informações sobre os campos, consulte CreateUploadAttachedMedia.

  • AliyunVodUploader.py

    Diretório

    Descrição

    uploadLocalVideo

    A API para upload de vídeos locais.

    uploadWebVideo

    A API para upload de vídeos da web.

    uploadLocalM3u8

    Faz upload de vídeos M3U8 locais.

    uploadWebM3u8

    Faz upload de vídeos M3U8 da web.

    uploadImage

    Faz upload de arquivos de imagem locais ou da web.

    uploadAttachedMedia

    Faz upload de arquivos de ativos de mídia auxiliares locais ou da web.

    parseWebM3u8

    Analisa as informações de shard de um arquivo M3U8 da web.

    parseLocalM3u8

    Analisa as informações de shard de um arquivo M3U8 local.

    setApiRegion

    Define o endpoint do VOD. O valor padrão é cn-shanghai (Shanghai). Regiões fora da China, como ap-southeast-1 (Singapore), também são compatíveis. Para mais informações, consulte VOD region IDs.

    setMultipartUpload

    Define o limiar e o tamanho da parte para upload multipart.

    uploadProgressCallback

    A função de callback para o progresso do upload. Você pode reescrever essa função.

    setEnableCrc

    Define se a verificação de redundância cíclica (CRC) será ativada durante o upload. Vem ativada por padrão.

  • ChangeLog.txt: Contém o histórico de lançamentos. A primeira linha indica o número da versão atual do SDK e a data de lançamento.

O diretório samples

  • uploadVideo.py: Código de exemplo para upload de vídeos.

  • uploadImage.py: Código de exemplo para upload de imagens.

  • uploadAttachedMedia.py: Código de exemplo para upload de arquivos de ativos de mídia auxiliares.

Cenário 1: Upload de arquivos de áudio e vídeo

Upload de arquivos comuns

É possível fazer upload dos seguintes tipos de arquivos de áudio e vídeo:

  • Arquivos locais: usa o upload multipart. O tamanho máximo de um único arquivo é de 48,8 TB. Não há suporte para upload retomável. Para mais informações, consulte a função testUploadLocalVideo no código de exemplo.

  • Arquivos da web: especifique uma URL de arquivo para o upload. O tamanho máximo de um único arquivo é de 48,8 TB. Este método exige o download do arquivo da web para um disco local antes do upload. Certifique-se de que o disco local tenha espaço suficiente. Para mais informações, consulte a função testUploadWebVideo no código de exemplo.

Clique para visualizar o código de exemplo

# -*- 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 de arquivos M3U8

Clique para visualizar o código de exemplo

# -*- 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)
            

Aceleração de upload

Para fazer upload de arquivos grandes (na ordem de GB ou TB) ou realizar uploads entre regiões, como enviar um vídeo da China continental para um endereço de armazenamento na região de Singapore, ative o recurso de aceleração de upload. Para mais informações, consulte Enable upload acceleration. Após ativar esse recurso, adicione o par AccelerateConfig chave-valor ao objeto UserData na configuração de upload. Se o objeto UserData não existir, crie-o. Veja um exemplo:

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

Descrição dos parâmetros

Nome

Tipo

Descrição

Type

string

O tipo de aceleração de upload a ser ativado. Apenas oss é compatível.

Domain

string

O nome de domínio acelerado do seu bucket. O protocolo padrão é HTTPS.

Nota

Use um nome de domínio acelerado atribuído após a ativação, por exemplo, vod-***.oss-accelerate.aliyuncs.com.

Cenário 2: Upload de imagens

Clique para visualizar o código de exemplo

# -*- 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)
            

Cenário 3: Upload de ativos de mídia auxiliares

Clique para visualizar o código de exemplo

# -*- 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)
            

Perguntas frequentes

Ao usar o código de exemplo para fazer upload de um fluxo de vídeo da web, se o erro ERROR:root:Download fail: [Errno 2] No such file or directory for relatado, resolva o problema criando manualmente uma pasta dlfiles no mesmo diretório da pasta voduploadsdk.

/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