上传功能函数说明--视频点播-火山引擎

文档中心

立即注册

视频点播

开发上传

上传功能函数说明

通过在上传视频时附加功能函数，您可以实现在上传完成的瞬间，自动执行一系列后续操作，例如视频截图、设置媒资信息或触发媒体处理工作流等。

如何传入上传功能函数

上传功能函数适用于以下两种上传方式：

若使用服务端上传：在调用 CommitUploadInfo 接口时，通过 Functions 参数传入。
若使用客户端上传：在调用 Web 上传 SDK 的 addFile(fileOption) 方法时，通过 processAction 参数传入。

参数说明

上传功能函数是一个可扩展的 JSON 数组，数组中的每个对象代表一个要执行的功能。

顶层结构

参数	类型	是否必选	说明
Name	String	是	功能名称。支持以下函数： `Snapshot`：视频截图。为上传的视频截取一帧作为封面。配置后，您可通过响应中的 `PosterUri` 字段获取截图存储地址。 `AddOptionInfo`：设置媒资信息。为上传的媒资设置标题、标签、分类等元数据。 `StartWorkflow`：触发工作流。上传完成后自动触发一个媒体处理工作流。注意媒资上传和工作流触发是异步的。即使工作流触发失败，也不会影响上传任务的提交成功。使用此方法时，请注意独立监测工作流的执行情况。 `CaptionUpload`：上传并绑定字幕。将一个字幕文件与指定的 `Vid` 进行关联。
Input	Object	否	功能配置。对于不同的上传功能，您可传入不同的配置，具体如下： SnapshotInput：视频截图配置。 OptionInfo：媒资信息配置。 WorkflowInput：触发工作流配置。 CaptionUpload：字幕上传配置。

参数

类型

是否必选

说明

Name

String

是

功能名称。支持以下函数：

Snapshot：视频截图。为上传的视频截取一帧作为封面。配置后，您可通过响应中的 PosterUri 字段获取截图存储地址。
AddOptionInfo：设置媒资信息。为上传的媒资设置标题、标签、分类等元数据。
StartWorkflow：触发工作流。上传完成后自动触发一个媒体处理工作流。

注意

媒资上传和工作流触发是异步的。即使工作流触发失败，也不会影响上传任务的提交成功。使用此方法时，请注意独立监测工作流的执行情况。

CaptionUpload：上传并绑定字幕。将一个字幕文件与指定的 Vid 进行关联。

Input

Object

否

功能配置。对于不同的上传功能，您可传入不同的配置，具体如下：

SnapshotInput：视频截图配置。
OptionInfo：媒资信息配置。
WorkflowInput：触发工作流配置。
CaptionUpload：字幕上传配置。

SnapshotInput

视频截图功能的配置参数。

参数	类型	是否必选	示例	描述
SnapshotTime	Float	否	`2`	截图时间点，单位为秒。系统将截取该时间点的视频帧作为封面。默认值为 0，表示截取视频首帧。

OptionInfo

媒资信息设置功能的配置参数。

参数	类型	是否必选	示例	描述
Title	String	否	`上传`	媒资标题。不超过 512 个字符。
Tags	String	否	`01`	媒资标签。多个标签以英文逗号分隔。
Description	String	否	`视频上传测试`	媒资描述。
RecordType	Integer	否	`1`	媒资类型。如不传，则默认为音视频。取值如下： `1`：音视频。 `2`：素材。说明音视频和素材的定义详见媒资上传概述。
Category	String	否	`video`	素材的具体类型。当 `RecordType` 参数取值为 `2` （素材）时，您必须传入 `Category` 参数指定素材类型。取值如下： `video`: 视频。 `audio`: 音频。 `image`: 图片。 `dynamic_img`: 动图。 `subtitle`: 字幕。 `font`: 字体。
Format	String	否	`mp4`	媒资格式。通常由系统自动识别，您也可以手动指定以覆盖识别结果。若遇到特殊文件无法识别，`Format` 可能为空。
ClassificationId	Int64	否	`1702994957`	音视频的分类 ID。当 `RecordType` 参数取值为 `1`（音视频）时，您可通过 `ClassificationId` 参数对音视频进行分类。音视频的分类是由您自行创建并管理的，方式如下：在视频点播控制台系统设置 > 分类管理页面创建。通过 CreateVideoClassification 接口创建。
IsHlsIndexOnly	Boolean	否	`true`	是否仅为 HLS 索引文件。取值如下： `true`: 仅为 HLS 索引文件。删除此 Vid 时，不会删除关联的 TS 文件。 `false`: （默认）删除此 Vid 时，会删除关联的 TS 文件。

WorkflowInput

触发工作流配置。

参数	类型	是否必选	示例	描述
Templates	Array of Template	否	`-`	工作流信息。上传完成后如果希望自动触发媒体处理工作流，可传入此参数。
TemplateId	String	否	`732db535401***8c234dc3aef`	工作流 ID。上传完成后如果希望自动触发媒体处理，可传入此参数。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。具体请见工作流。注意 `TemplateId` 已废弃，推荐使用 `Templates` 参数。

Template

工作流信息。

参数	类型	是否必选	示例	描述
TemplateIds	[]string	否	`["abcd***123"]`	工作流 ID。上传完成后如果希望自动触发媒体处理，可传入此参数。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。具体请见工作流。当前仅支持单个工作流 ID。
TemplateType	String	否	`transcode`	工作流类型。取值如下： `transcode`: （默认）在视频点播服务中创建的工作流。 `imp`: 在智能处理服务中创建的工作流。

参数

类型

是否必选

示例

描述

TemplateIds

[]string

否

["abcd***123"]

工作流 ID。上传完成后如果希望自动触发媒体处理，可传入此参数。可在视频点播控制台媒体处理 > 工作流页面获取工作流 ID。具体请见工作流。当前仅支持单个工作流 ID。

TemplateType

String

否

transcode

工作流类型。取值如下：

transcode: （默认）在视频点播服务中创建的工作流。
imp: 在智能处理服务中创建的工作流。

CaptionUpload

字幕上传配置。

参数	类型	是否必选	示例	描述
Vid	String	是	`v03c***eg0`	要绑定字幕的视频 Vid。
Fid	String	是	`v03c***eg0`	字幕文件的 ID，可与 `Vid` 保持一致。
Language	String	是	`eng-US`	字幕语言。具体取值请参见字幕语言。
Format	String	是	`webvtt`	字幕格式。取值如下： `webvtt` `ass` `srt` `ssa` 注意当字幕格式为 `webvtt` 时，不支持上传带序号行的字幕文件。
StoreUri	String	否	`tos-vod-cn-v-03e4d54ef31***66a7d8c39f`	字幕文件的存储 URI。
Title	String	否	`test`	字幕标题。最长 128 字符。不传为不修改，传空为置空。
Source	String	否	`MU`	字幕来源。取值如下： `MT`：机器翻译 `ASR`：语音转写 `MU`：（默认）人工上传
Tag	String	否	`01`	字幕标签。最长 128 字符。不传为不修改，传空为置空。
AutoPublish	Boolean	否	`true`	是否自动发布。取值如下： `true`：自动发布 `false`：（默认）不自动发布
ActionType	String	否	`upload`	操作类型。取值如下： `upload`：（默认）上传 `replace`：替换

请求示例

以下示例展示了如何在上传时，同时执行在第 2 秒截图和设置媒资标题两个功能。

[
    {
      "Name": "Snapshot",
      "Input": {
        "SnapshotTime": 2.0
      }
    },
    {
      "Name": "AddOptionInfo",
      "Input": {
        "Title": "我的视频"
      }
    }
]

`FileType` 和 `Category` 的对应关系

FileType 参数取值和 Category 参数取值的对应关系如下表所示：

FileType 取值	对应 Category 取值
`media`	`video`：视频。 `audio`：音频。
`image`	`image`：图片。 `dynamic_img`：动图。
`object`	`subtitle`：字幕。 `font`：字体。

最近更新时间：2025.12.24 11:44:56

这个页面对您有帮助吗？

有用

无用