媒资上传--视频点播-火山引擎

文档中心

立即注册

导航

媒资上传

最近更新时间：2025.05.13 19:35:44首次发布时间：2021.02.23 10:42:40

本文为您介绍如何使用视频点播服务端 Python SDK 将音频、视频、图片等媒资文件上传至视频点播服务。

费用说明

媒资上传到视频点播中会产生存储费用，具体参见媒资存储计费。

前提条件

已完成 Python SDK 的安装和初始化。
已创建空间。
上传前，请确保您已阅读媒资上传概述了解媒资上传功能、视频点播支持的媒资类型、格式和大小限制。

上传音视频

直接上传本地文件

视频点播服务端 SDK 封装了 ApplyUploadInfo - 获取上传地址和凭证和 CommitUploadInfo - 确认上传接口以及上传逻辑，您只需简单配置即可进行上传。

说明

完整的上传流程请见服务端上传。
上传任务成功提交后，您可通过媒资上传完成事件通知获取任务结果。配置方式请见事件通知概述。
上传文件时必须携带文件后缀。例如，如需上传 MP4 文件，携带 .mp4 或 .MP4。
以下示例为 2022-01-01 版本的 ApplyUploadInfo 和 CommitUploadInfo 接口。如您使用 2020-08-01 版本，示例代码请见历史版本。

# coding:utf-8
from __future__ import print_function

import json

from volcengine.util.Functions import Function
from volcengine.vod.VodService import VodService
from volcengine.vod.models.request.request_vod_pb2 import VodUploadMediaRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    space_name = 'your space name'
    file_path = 'your file path'

    get_meta_function = Function.get_meta_func()
    snapshot_function = Function.get_snapshot_func(2.3)
    get_start_workflow_func = Function.get_start_workflow_template_func(
        [{"TemplateIds": ["imp template id"], "TemplateType": "imp"},
         {"TemplateIds": ["transcode template id"], "TemplateType": "transcode"}])
    apply_function = Function.get_add_option_info_func("title1", "tag1", "desc1", 0, False)

    try:
        req = VodUploadMediaRequest()
        req.SpaceName = space_name
        req.FilePath = file_path
        req.Functions = json.dumps([get_meta_function, snapshot_function, get_start_workflow_func])
        req.CallbackArgs = ''
        req.FileName = 'hello/vod.mp4'
        req.FileExtension = '.mp4'
        req.StorageClass = 1
        req.UploadHostPrefer = ''
        resp = vod_service.upload_media(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.Vid)
            print(resp.Result.Data.PosterUri)
            print(resp.Result.Data.SourceInfo.FileName)
            print(resp.Result.Data.SourceInfo.Height)
            print(resp.Result.Data.SourceInfo.Width)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

URL 批量拉取上传

视频点播服务端 SDK 封装了 URL 批量拉取上传 - UploadMediaByUrl 接口，您只需简单配置即可进行上传。完整的上传流程请见服务端上传。

说明

本接口主要适用于文件没有存储在本地服务器或终端，需要通过公网访问的 URL 地址上传的场景。源文件 URL 支持 HTTP 和 HTTPS。
本接口为异步上传接口。上传任务成功提交后，系统会生成异步执行的任务，排队执行，不保证时效性。
本接口的请求参数和返回参数说明详见 UploadMediaByUrl。
上传任务成功提交后，可通过以下方式获取任务结果：
- 调用 QueryUploadTaskInfo 接口查询 URL 批量上传任务状态。
- 配置 URL 批量拉取上传完成事件通知。每个 URL 上传完成时您都将收到通知。配置方式请见事件通知概述。

# coding:utf-8
from __future__ import print_function

from volcengine.vod.VodService import VodService
from volcengine.vod.models.request.request_vod_pb2 import VodUrlUploadRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    space_name = 'your space'
    url = ''

    try:
        req = VodUrlUploadRequest()
        req.SpaceName = space_name
        url_set = req.URLSets.add()
        url_set.SourceUrl = url
        url_set.FileExtension = '.mp4'
        url_set.CallbackArgs = 'my python callback args'
        customUrlHeaders = {'your header key': 'your header value'}
        url_set.CustomURLHeaders.update(**customUrlHeaders)
        resp = vod_service.upload_media_by_url(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data[0].JobId)
            print(resp.Result.Data[0].SourceUrl)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

上传素材

视频点播服务端 SDK 封装了 ApplyUploadInfo - 获取上传地址和凭证和 CommitUploadInfo - 确认上传接口以及上传逻辑，您只需简单配置即可进行上传。

说明

完整的上传流程请见服务端上传。
上传任务成功提交后，您可通过素材上传完成事件通知获取任务结果。配置方式请见事件通知概述。
上传文件时必须携带文件后缀。例如，如需上传 MP4 文件，携带 .mp4 或 .MP4。
以下示例为 2022-01-01 版本的 ApplyUploadInfo 和 CommitUploadInfo 接口。如您使用 2020-08-01 版本，示例代码请见历史版本。

# coding:utf-8
from __future__ import print_function

import json

from volcengine.util.Functions import Function
from volcengine.vod.VodService import VodService
from volcengine.const.Const import *
from volcengine.vod.models.request.request_vod_pb2 import VodUploadMaterialRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    space_name = 'your space name'
    file_path = 'your file path'

    get_meta_function = Function.get_meta_func()
    snapshot_function = Function.get_snapshot_func(2.3)
    add_option_function = Function.get_add_material_option_info_func(title='素材测试视频', tags='test',
                                                                     description='素材测试，视频文件',
                                                                     category=CATEGORY_VIDEO, record_type=2,
                                                                     format_input='MP4')

    try:
        req = VodUploadMaterialRequest()
        req.FileType = FILE_TYPE_MEDIA
        req.SpaceName = space_name
        req.FilePath = file_path
        req.Functions = json.dumps([get_meta_function, snapshot_function, add_option_function])
        req.CallbackArgs = ''
        req.FileExtension = '.mp4'
        req.UploadHostPrefer = ''

        resp = vod_service.upload_material(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.Mid)
            print(resp.Result.Data.PosterUri)
            print(resp.Result.Data.SourceInfo.FileName)
            print(resp.Result.Data.SourceInfo.Height)
            print(resp.Result.Data.SourceInfo.Width)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

if __name__ == '__main__':
    vod_service = VodService()

    # call below method if you dont set ak and sk in $HOME/.vcloud/config
    vod_service.set_ak('your ak')
    vod_service.set_sk('your sk')

    space_name = 'your space name'
    file_path = 'your file path'

    get_meta_function = Function.get_meta_func()
    snapshot_function = Function.get_snapshot_func(0)
    add_option_function = Function.get_add_material_option_info_func(title='素材测试图片', tags='test',
                                                                     description='素材测试，图片文件',
                                                                     category=CATEGORY_IMAGE, record_type=2,
                                                                     format_input='jpg')

    try:
        req = VodUploadMaterialRequest()
        req.FileType = FILE_TYPE_IMAGE
        req.SpaceName = space_name
        req.FilePath = file_path
        req.Functions = json.dumps([get_meta_function, snapshot_function, add_option_function])
        req.CallbackArgs = ''
        req.FileName = ''
        req.FileExtension = '.jpg'
        req.UploadHostPrefer = ''

        resp = vod_service.upload_material(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.Mid)
            print(resp.Result.Data.PosterUri)
            print(resp.Result.Data.SourceInfo.FileName)
            print(resp.Result.Data.SourceInfo.Height)
            print(resp.Result.Data.SourceInfo.Width)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

if __name__ == '__main__':
    vod_service = VodService()

    # call below method if you dont set ak and sk in $HOME/.vcloud/config
    vod_service.set_ak('your ak')
    vod_service.set_sk('your sk')

    space_name = 'your space name'
    file_path = 'your file path'

    get_meta_function = Function.get_meta_func()
    add_option_function = Function.get_add_material_option_info_func(title='素材测试字幕', tags='test',
                                                                     description='素材测试，字幕文件',
                                                                     category=CATEGORY_FONT, record_type=2,
                                                                     format_input='vtt')

    try:
        req = VodUploadMaterialRequest()
        req.FileType = FILE_TYPE_OBJECT
        req.SpaceName = space_name
        req.FilePath = file_path
        req.Functions = json.dumps([get_meta_function, add_option_function])
        req.CallbackArgs = ''
        req.FileName = ''
        req.FileExtension = '.vtt'
        req.UploadHostPrefer = ''

        resp = vod_service.upload_material(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.Mid)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

后续操作

查看上传结果

您可以通过配置上传事件通知及时获取上传的进展和状态，详细介绍请见上传事件通知。

上传后自动转码

您可以通过工作流实现上传后自动转码，详细介绍请见工作流。

发布音视频

音视频资源上传至视频点播服务之后，默认为未发布状态，此时无法获取到播放地址。因此在音视频播放前，您需要先修改音视频状态为已发布。具体操作请参见修改音视频发布状态。

常见问题

我在上传过程中通过 `FileName` 参数设置了文件名称，但上传后控制台显示"未命名"，为什么没有显示我设置的文件名称？

这是因为在视频点播服务中，FileName 参数实际上指的是文件路径（即媒资在存储桶中的唯一标识和存储位置），而不是用户可见的文件名称。如需设置控制台显示的文件名称，您需要通过上传功能函数设置 FileTitle 参数。详见上传功能函数说明。

RecordType、FileType、Category 这三个参数的区别及如何设置？

参数	说明
FileType	作用：在 `ApplyUploadInfo` 接口中指定文件类型，用于分配不同的上传域名。取值： `media`：（默认）音视频文件（如 MP4、MP3）。 `image`：图片文件（如 JPG、PNG）。 `object`：其他类型文件（如字幕、字体）。
RecordType	作用：在 `CommitUploadInfo` 接口的上传功能函数中指定媒资类型，决定生成音视频或素材的元数据。取值： `1`：（默认）音视频。 `2`：素材（如图片、字幕、字体等）。
Category	作用：当 `RecordType` 为 `2`（素材）时，进一步细化素材类型。取值：`video`、`audio`、`image`、`dynamic_img`、`subtitle`、`font` 等。

通过正确组合这三个参数，可确保文件上传至正确的域名并生成匹配的元数据。示例：

上传音视频（如 MP4）
- FileType 设为 media 或留空。
- RecordType 设为 1 或留空。
- Category 无需设置（仅当 RecordType=2 时生效）。
上传素材图片（如 JPG）
- FileType 设为 image（图片使用图片上传域名）。
- RecordType 设为 2（素材）。
- Category 设为 image（进一步指定为图片素材）。
上传字幕文件（如 SRT）
- FileType 设为 object（非音视频/图片的文件类型）。
- RecordType 设为 2（素材）。
- Category 设为 subtitle（进一步指定为字幕素材）。

说明

通过服务端 SDK 上传素材时，接口已默认设置 RecordType 为 2，用户无需再设置。

如果我想在上传后对媒资进行分类，该如何操作？

视频点播当前仅支持手动分类。您可在视频点播控制台指定空间内的分类管理页面创建分类并获取分类 ID，具体请见分类管理。

更多示例

签发临时上传 Token

如果您使用客户端上传 SDK 进行上传，您需要在应用服务端通过 AK 和 SK 在本地签出临时上传 Token，不依赖外网。如希望同时生成多个临时上传 Token，您可以循环调用生成方法。临时上传 Token 用于客户端上传，详见客户端上传。

# coding:utf-8
from __future__ import print_function

from volcengine.vod.VodService import VodService

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    sts2 = vod_service.get_upload_sts2_with_expired_time(60 * 60)
    print(sts2)

    sts2 = vod_service.get_upload_sts2()
    print(sts2)

获取上传地址和凭证

接口请求参数和返回参数说明详见 ApplyUploadInfo。

# coding:utf-8
from __future__ import print_function

from volcengine.vod.VodService import VodService
from volcengine.vod.models.request.request_vod_pb2 import VodApplyUploadInfoRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    space_name = 'your space'

    try:
        req = VodApplyUploadInfoRequest()
        req.SpaceName = space_name

        resp = vod_service.apply_upload_info(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.UploadAddress.StoreInfos[0].StoreUri)
            print(resp.Result.Data.UploadAddress.StoreInfos[0].Auth)
            print(resp.Result.Data.UploadAddress.UploadHosts[0])
            print(resp.Result.Data.UploadAddress.SessionKey)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

查询 URL 上传任务状态

接口请求参数和返回参数详见OpenAPI：查询URL批量上传任务状态。

# coding:utf-8
from __future__ import print_function

from volcengine.vod.VodService import VodService
from volcengine.vod.models.request.request_vod_pb2 import VodQueryUploadTaskInfoRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    jobId = 'url jobId'

    jobIds = [jobId]
    comma = ','
    s = comma.join(jobIds)

    req = VodQueryUploadTaskInfoRequest()
    req.JobIds = s
    try:
        resp = vod_service.query_upload_task_info(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.MediaInfoList[0].State)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

历史版本

2020-08-01 上传音视频

接口请求参数和返回参数说明详见 ApplyUploadInfo 及 CommitUploadInfo。

# coding:utf-8
from __future__ import print_function

import json

from volcengine.util.Functions import Function
from volcengine.vod.VodService import VodService
from volcengine.vod.models.request.request_vod_pb2 import VodUploadMediaRequest

if __name__ == '__main__':
    # Create a VOD instance in the specified region.
    # vod_service = VodService('cn-north-1')
    vod_service = VodService()

    # Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65646.
    # The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
    # During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
    # vod_service.set_ak('your ak')
    # vod_service.set_sk('your sk')

    space_name = 'your space name'
    file_path = 'your file path'

    get_meta_function = Function.get_meta_func()
    snapshot_function = Function.get_snapshot_func(2.3)

    try:
        req = VodUploadMediaRequest()
        req.SpaceName = space_name
        req.FilePath = file_path
        req.Functions = json.dumps([get_meta_function, snapshot_function])
        req.CallbackArgs = ''
        req.FileName = ''

        resp = vod_service.upload_media(req)
    except Exception:
        raise
    else:
        print(resp)
        if resp.ResponseMetadata.Error.Code == '':
            print(resp.Result.Data)
            print(resp.Result.Data.Vid)
            print(resp.Result.Data.PosterUri)
            print(resp.Result.Data.SourceInfo.Height)
            print(resp.Result.Data.SourceInfo.Width)
        else:
            print(resp.ResponseMetadata.Error)
            print(resp.ResponseMetadata.RequestId)

2020-08-01 上传素材