触发工作流--视频点播-火山引擎

文档中心

立即注册

导航

触发工作流

最近更新时间：2024.12.11 16:14:51首次发布时间：2021.02.23 10:42:37

此接口用于指定工作流 ID 来触发媒体处理任务，以对指定片源进行媒体处理。

使用说明

成功提交后，系统将生成异步执行的媒体处理任务。如需获取媒体处理结果，可配置工作流执行完成事件通知。
工作流幂等行为、目的和条件等内容请见工作流幂等说明。
更多信息，请见触发工作流常见请求示例。

注意事项

优先级：本接口的参数设置优先级高于视频点播控制台媒体处理模板和工作流中的参数设置。

请求说明

请求地址：https://vod.volcengineapi.com?Action=StartWorkflow&Version=2020-08-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

参数	类型	是否必选	示例值	描述
Action	String	是	`StartWorkflow`	接口名称。当前 API 的名称为 `StartWorkflow`。
Version	String	是	`2020-08-01`	接口版本。当前 API 的版本为 `2020-08-01`。
Vid	String	否	`v023bbg10001***2n6qiboeb9dn73mg`	视频 ID。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 `Vid`。注意您必须设置 `Vid` 或 `DirectUrl` 参数之一，但不能同时设置这两个参数。
DirectUrl	Object of DirectUrl	否	`-`	DirectUrl 模式下的文件存储信息。注意您必须设置 `Vid` 或 `DirectUrl` 参数之一，但不能同时设置这两个参数。如果是 POST 请求，该参数类型为 String。示例： `"{\"FileName\":\"example.mp4\"}"`
TemplateId	String	是	`63d92a1***b1795`	工作流 ID。您可在视频点播控制台创建工作流并获取工作流 ID，详见工作流。
Input	Object of WorkflowParams	否	`-`	动态参数。默认情况下，视频点播根据工作流及其关联的媒体处理模板中的预设参数执行媒体处理任务。如果您需要在触发工作流时动态设置处理参数，例如设置输出文件路径或文字水印内容，您可以传入动态参数。动态参数将覆盖指定模板中相应参数的内容。说明如果是 POST 请求，该参数类型为 String。示例： `"{\"OverrideParams\":{\"Logo\":[{\"Vars\":{\"input_text\":\"文字水印测试\"}}]}}"`
Priority	Integer	否	`0`	任务优先级。默认值为 0。取值范围为 [-5,5]。数字越小，优先级越高。
CallbackArgs	String	否	`YourCallbackArgs`	自定义字段，将在工作流执行完成事件中透传返回。字段长度最大为 512 字节。
EnableLowPriority	Boolean	否	`false`	是否开启闲时转码。取值如下： `true`：开启。 `false`：关闭。说明对于闲时转码功能的介绍和使用场景，请见闲时转码。

DirectUrl

参数	类型	是否必选	示例值	描述
SpaceName	String	否	`test`	空间名称。可调用 ListSpace 获取当前账号下所有空间的信息。注意若您触发的工作流是系统内置工作流，则 `SpaceName` 必填。
FileName	String	是	`example.mp4`	文件路径。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 `FileName`。
BucketName	String	否	`tos-cn-v-cd3a11`	存储桶名称。可调用 ListSpace 获取空间所绑定的存储桶名称。

WorkflowParams

参数	类型	是否必选	示例值	描述
OverrideParams	Object of OverrideParams	否	`-`	覆盖参数，用于覆盖媒体处理模板中的配置。

OverrideParams

参数	类型	是否必选	示例值	描述
Logo	Array of LogoOverride	否	`[{"TemplateId":"1091058d***6b8f408c352ee1c52","Vars":{"keyword":"hello"}}]`	水印覆盖参数。
Snapshot	Array of SnapshotOverride	否	`[{"TemplateId": ["94c8d47c4c39440b8***e0ce7a96776"],"FileName": "{{fileTitle}}_{{templateId}}"}]`	截图覆盖参数。
TranscodeAudio	Array of TranscodeAudioOverride	否	`[{"TemplateId":["1091058d***6b8f408c352ee1c52"],"Clip":{"StartTime":0,"EndTime":20000}}]`	音频转码覆盖参数。
TranscodeVideo	Array of TranscodeVideoOverride	否	`[{"TemplateId":["1091058d***6b8f408c352ee1c52"],"Clip":{"StartTime":0,"EndTime":20000}}]`	视频转码覆盖参数。

LogoOverride

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
Vars	JSON Map	否	`{"keyword":"hello"}`	水印覆盖内容。格式为 `"key":"value"`。 `"key"`：String 类型。该值为您在水印贴片模板中配置的自定义变量 key。具体步骤，请见动态替换文字水印内容。 `"value"`：String 类型。该值为自定义文字水印内容。
TemplateId	String	是	`1091058d0**6b8f408c352ee1c52`	水印贴片模板 ID。支持设为 `All`，表示对所有水印贴片模板生效。

Vars

JSON Map

否

{"keyword":"hello"}

水印覆盖内容。格式为 "key":"value"。

"key"：String 类型。该值为您在水印贴片模板中配置的自定义变量 key。具体步骤，请见动态替换文字水印内容。
"value"：String 类型。该值为自定义文字水印内容。

TemplateId String 是 1091058d0**6b8f408c352ee1c52 水印贴片模板 ID。支持设为 All，表示对所有水印贴片模板生效。

SnapshotOverride

参数	类型	是否必选	示例值	描述
FileName	String	否	`{{fileTitle}}`	动态设置截图文件路径。文件路径可由固定字符串和变量组成，详见文件路径组成说明。假设你对文件名称为 `vodtest` 的片源触发工作流 `a378f66a5bc2495eb55fc14ac109625f`，并将 `FileName` 设为 `{{fileTitle}}_{{templateId}}`，则此次截图生成的文件路径为 `vodtest_a378f66a5bc2495eb55fc14ac109625f`。注意封装格式为 DASH 时，该参数不生效。
FileIndex	String	否	`{{fileTitle}}`	动态设置采样截图 index 文件路径。仅当截图类型为采样截图时生效。文件路径可由固定字符串和变量组成，详见文件路径组成说明。假设你对文件名称为 `vodtest` 的片源触发工作流 `a378f66a5bc2495eb55fc14ac109625f`，并将 `FileIndex` 设为 `{{fileTitle}}_{{templateId}}`，则此次截图生成的文件路径为 `vodtest_a378f66a5bc2495eb55fc14ac109625f`。
OffsetTime	Integer	否	`100`	截图时间间隔。单位为毫秒。仅当截图类型为静态图、动图、反复循环动图时生效。
TemplateId	Array of String	是	`["1091058d0**6b8f408c352ee1c52"]`	截图模板 ID 列表。支持取值为 `All`，表示不区分模板，只要为该类型就生效。
SampleOffsets	Array of Float	否	`[1.0,2.0]`	采样截图时间点。单位为秒。针对 `Sample` 类型截图模板有效。
OffsetTimeList	Array of Integer	否	`[10,20]`	多动图截图时间。单位为毫秒。针对 `Dynpost` 类型截图模板有效。
Width	Integer	否	`480`	采样截图宽度，单位为 px。取值范围为 [0, 4096]。不传 `Width` 时，按照采样截图模板中配置的宽度进行截图。 `Width` 为 `0` 时，根据 `Height` 的值按照片源宽高比进行缩放。 `Width` 和 `Height` 均为 `0` 时，按照片源尺寸截图。注意当前仅支持采样截图，且仅在采样截图模板中图片尺寸设为固定尺寸时生效。
Height	Integer	否	`720`	采样截图高度，单位为 px。取值范围为 [0, 4096]。不传 `Height` 时，按照采样截图模板中配置的高度进行截图。 `Height` 为 `0` 时，根据 `Width` 的值按照片源宽高比进行缩放。 `Width` 和 `Height` 均为 `0` 时，按照片源尺寸截图。注意当前仅支持采样截图，且仅在采样截图模板中图片尺寸设为固定尺寸时生效。

TranscodeAudioOverride

参数	类型	是否必选	示例值	描述
Clip	Object of Clip	否	`{"StartTime":0,"EndTime":20000}`	裁剪参数。
FileName	String	否	`{{fileTitle}}`	动态设置转码输出视频的文件路径。文件路径可由固定字符串和变量组成，详见文件路径组成说明。假设你对文件名称为 `vodtest` 的片源触发工作流 `a378f66a5bc2495eb55fc14ac109625f`，并将 `FileName` 设为 `{{fileTitle}}_{{templateId}}`，则此次转码生成的文件路径为 `vodtest_a378f66a5bc2495eb55fc14ac109625f`。注意封装格式为 DASH 时，该参数不生效。
TemplateId	Array of String	是	`["1091058d0**6b8f408c352ee1c52"]`	音频转码模板 ID 列表。支持 `All` 取值，此时不区分模板，只要为该类型就生效。

TranscodeVideoOverride

参数	类型	是否必选	示例值	描述
Clip	Object of Clip	否	`{"StartTime":0,"EndTime":20000}`	裁剪参数。
FileName	String	否	`{{fileName}}`	动态设置转码输出视频的文件路径。文件路径可由固定字符串和变量组成，详见文件路径组成说明。假设你对文件名称为 `vodtest` 的片源触发工作流 `a378f66a5bc2495eb55fc14ac109625f`，并将 `FileName` 设为 `{{fileTitle}}_{{templateId}}`，则此次转码生成的文件路径为 `vodtest_a378f66a5bc2495eb55fc14ac109625f`。注意封装格式为 DASH 时，该参数不生效。
TemplateId	Array of String	是	`["1091058****6b8f408c352ee1c52"]`	视频处理模板或极智超清模板 ID 列表。支持取值为 `All`，表示不区分模板，只要为该类型就生效。
LogoTemplateId	String	否	`1091058****6b8f408c352ee1c52`	水印贴片模板 ID。该参数仅当 `TemplateId` 所对应的模板是视频转码或极智超清类型时生效。

Clip

参数	类型	是否必选	示例值	描述
StartTime	Integer	否	`0`	裁剪开始时间，单位为毫秒。
EndTime	Integer	否	`2000`	裁剪结束时间，单位为毫秒。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
RunId	String	`lb:0f557116******059cedf92f1bd`	工作流执行 ID。

请求示例

https://vod.volcengineapi.com?Action=StartWorkflow&Version=2020-08-01&TemplateId=63d92a1***b1795&EnableLowPriority=true&DirectUrl={"FileName":"input_test.mp4"}

返回示例

{
  "ResponseMetadata": {
    "RequestId": "202208121******514515206772F7C",
    "Action": "StartWorkflow",
    "Version": "2020-08-01",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": {
    "RunId": "lb:0f557116******059cedf92f1bd"
  }
}

错误码

下表列举了本接口特有的错误码。如需了解更多错误码，详见视频点播公共错误码。

状态码	错误码	错误信息	说明
400	InvalidParameter	-	非法参数。
403	RequestForbidden	-	请求被禁止。
404	ResourceNotFound	-	ID 找不到。
409	ResourceInUse	-	ID 正在被使用（删除时）。
429	RequestLimitExceeded	-	请求超过上限。
500	InternalError	-	内部错误。
503	ServiceUnavailable	-	服务不可用。

SDK

点播 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API。此 API 各语言调用的示例代码，请参考如下：