CreateVideoTask - 创建视频质检任务--企业直播-火山引擎

文档中心

企业直播

视频质检 API

CreateVideoTask - 创建视频质检任务

调用 CreateVideoTask 接口，创建视频质检任务。任务成功创建后，将返回任务 ID。您可通过该任务 ID，调用 GetVideoReport 接口，获取视频质检报告。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。
前提条件：确保当前账号已开通质检服务。若当前账号为子账号，请同时确保主账号已在直播质检平台为该子账号授权，详见为子账号授权。否则账号将提示“暂无使用权限,请联系客服人员申请开通”。

请求说明

请求方式：POST
请求地址：https://livesaas.volcengineapi.com/?Action=CreateVideoTask&Version=2024-08-01

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateVideoTask`	接口名称。当前 API 的名称为 `CreateVideoTask`。
Version	String	是	`2024-08-01`	接口版本。当前 API 的版本为 `2024-08-01`。

Body

参数	类型	是否必选	示例值	描述
ProjectName	String	是	`1827*****8608457`	视频质检项目名称。您可通过调用 ListProjects 接口获取项目名称。
TaskName	String	是	`视频质检任务 A`	视频质检任务名称，长度为 1 到 200 个字符。支持模糊搜索，英文不区分大小写。支持以下字符：中文数字大写字母 A - Z 小写字母 a - z
ScenarioId	Long	是	`1`	视频质检项目中的审核场景 ID。您可通过调用 ListVideoScenarios 接口获取 ID。
SourceType	Integer	是	`3`	待审视频的数据源类型。取值如下： `1`：当前项目的视频管理库 `3`：质检回放视频，即当前账号可见的直播质检任务中的直播回放视频 `4`：通过视频 URL 地址提供的视频
TaskItems	Array of TaskItems	是	`-`	待审视频数据。注意当前仅支持传入单个视频数据。
CallbackURL	String	否	`https://callback.example.com/inspect`	视频质检消息回调地址。支持 HTTP 和 HTTPS 协议头。请使用可公网访问的域名地址，不支持配置 IPv4 地址（例如 `http://1.2.3.4/callback`）。说明如需通过视频质检消息回调获取任务状态消息、机审违规消息，以及人审处置意见消息，该参数必选。视频质检服务会将质检结果以 `POST` 方法提交至该地址。请求体为 JSON 格式。详见视频质检消息回调。
Extra	String	否	`extra`	需要透传的业务相关信息。长度为 1 到 1000 个字符。仅用于信息透传，不做其他处理。
TagIds	Array of Long	否	`[121]`	标签 ID，用于绑定质检任务。每个质检任务最多支持绑定 10 个标签。说明父标签 ID 不生效。
SpecifiableRuleArgs	Array of SpecifiableRuleArgs	否	`-`	在创建视频审核任务时，若您指定的审核场景中，需要指定预设文字、字幕或脚本，则需要传入该字段。说明仅基于 OCR 文字模型、OCR 滚动字幕模型和 ASR 脚本对比模型创建的规则，支持在创建任务时指定预设的文字、字幕或脚本。

TaskItems

参数	类型	是否必选	示例值	描述
Vid	String	否	`v02eag10000***ctk`	当视频的数据源为视频管理库或本地上传视频时，视频的唯一标识。说明当 `SourceType` 取值为 `1` 时，该参数生效且必填。
Url	String	否	`https://example.com/videos/demo.mp4`	当视频的数据源为视频 URL 地址时，传入公网可访问的视频的 URL。支持 HTTP/HTTPS 协议头。支持 MP4 或 M3U8 格式的视频。说明当 `SourceType` 取值为 `4` 时，该参数生效且必填。
SourceTaskId	Long	否	`397***71`	当视频的数据源为直播质检任务中的回放视频时，传入直播质检任务的 ID。您可通过调用 ListTasks 接口获取 ID。说明当 `SourceType` 取值为 `3` 时，该参数生效且必填。
VideoName	String	否	`video.mp4`	当视频的数据源为视频 URL 地址时，您可通过此参数定义视频的名称。若不传，视频名称将从 URL 地址提取。例如，若视频地址为 `https://example.com/videos/demo.mp4`，则视频的默认名称为 `demo.mp4`。说明当 `SourceType` 取值为 `4` 时，该参数生效。当 `SourceType` 取值为 `1` 时，视频名称固定为原视频名称。当 `SourceType` 取值为 `3` 时，视频名称固定为直播质检的任务名称。

SpecifiableRuleArgs

参数	类型	是否必选	示例值	描述
RuleId	Long	是	`4005`	预设文字、字幕或脚本的审核规则 ID。可通过 GetVideoScenario 接口获取。
OcrTextRecognitionArgs	Object of OcrTextRecognitionArgs	否	`-`	若当前规则为基于 OCR 文字识别模型创建的规则，则需要传入自定义规则参数，即为当前任务预设的文字。说明当 `RuleId` 有值时，在 `OcrTextRecognitionArgs`、`OcrScrollingSubtitlesArgs` 和 `PresetScriptArgs` 这三个参数中，您必须且只能传入一个。
OcrScrollingSubtitlesArgs	Object of OcrScrollingSubtitlesArgs	否	`-`	若当前规则为基于 OCR 滚动字幕模型创建的规则，则需要传入自定义规则参数，即为当前任务预设的字幕。说明当 `RuleId` 有值时，在 `OcrTextRecognitionArgs`、`OcrScrollingSubtitlesArgs` 和 `PresetScriptArgs` 这三个参数中，您必须且只能传入一个。
PresetScriptArgs	Object of PresetScriptArgs	否	`-`	若当前规则为预设脚本对比规则，则需要传入预设脚本。说明当 `RuleId` 有值时，在 `OcrTextRecognitionArgs`、`OcrScrollingSubtitlesArgs` 和 `PresetScriptArgs` 这三个参数中，您必须且只能传入一个。

OcrTextRecognitionArgs

参数	类型	是否必选	示例值	描述
PresetText	String	否	`品牌名称`	预设文字。

OcrScrollingSubtitlesArgs

参数	类型	是否必选	示例值	描述
PresetSubtitles	String	否	`最`	预设的字幕，最多支持 200 个字符。说明若当前规则无需传入预设字幕，则传入的值将被忽略。

PresetScriptArgs

参数	类型	是否必选	示例值	描述
PresetScript	String	否	`标准讲解话术`	预设脚本，最多支持 20,000 个字符。说明若当前规则无需传入预设脚本，则传入的值将被忽略。

返回参数

参数	类型	示例值	描述
TotalCount	Integer	`1`	请求创建的视频质检任务总数。
SuccessCount	Integer	`1`	创建成功的视频质检任务数量。
FailedCount	Integer	`0`	创建失败的视频任务数量。
SuccessTasks	Array of SuccessTasks	`-`	创建成功的任务数据。
FailedTasks	Array of FailedTasks	`-`	创建失败的任务数据。

SuccessTasks

参数类型示例值描述

Index Integer 0 当前视频质检任务项在请求参数 TaskItems 数组中的位置索引，从 0 开始计数。

SourceId

String

example.com/video.mp4

用于定位原视频数据的标识。取值规则如下：

当 SourceType 取值为 1 时，该字段为视频的 VID，即请求参数 TaskItems[].Vid 的值。
当 SourceType 取值为 3 时，该字段为源质检任务 ID，即请求参数 TaskItems[].SourceTaskId 转换为字符串后的值。
当 SourceType 取值为 4 时，该字段为请求参数 TaskItems[].Url 的值，但会移除 Query 参数，仅保留协议、域名及路径部分，以避免返回鉴权信息、Token 等敏感数据。

TaskId Long 397***71 创建成功的视频质检任务 ID。您可通过该任务 ID，调用 GetVideoReport 接口，获取视频质检报告。

FailedTasks

参数	类型	示例值	描述
Index	Integer	`0`	当前视频质检任务项在请求参数 `TaskItems` 数组中的位置索引，从 `0` 开始计数。
SourceId	String	`example.com/video.mp4`	用于定位原视频数据的标识。取值规则如下：当 `SourceType` 取值为 `1` 时，该字段为视频的 VID，即请求参数 `TaskItems[].Vid` 的值。当 `SourceType` 取值为 `3` 时，该字段为源质检任务 ID，即请求参数 `TaskItems[].SourceTaskId` 转换为字符串后的值。当 `SourceType` 取值为 `4` 时，该字段为请求参数 `TaskItems[].Url` 的值，但会移除 Query 参数，仅保留协议、域名及路径部分，以避免返回鉴权信息、Token 等敏感数据。
ErrorCode	String	`InvalidURL`	创建失败的错误码。取值如下： `InvalidVid`：视频 ID（Vid）不能为空。请检查请求参数 `TaskItems[].Vid` 的值。仅当 `SourceType` 取值为 `1` 时返回。 `VodError`：获取视频点播信息失败，视频可能尚未完成同步。请稍后重试。 `VodMetaError`：获取视频元数据失败，视频元数据信息不存在或不完整。检查视频 `SourceTaskIdError`：获取源任务信息失败，请检查原直播质检中的回放视频。 `NoReplayRecord`：未找到对应的直播回放文件。请检查原直播质检中的回放视频。 `TaskProcessTimeExceedLimit`：视频时长超出任务处理的 3 小时时长限制。请检查视频时长。 `InvalidURL`：URL 格式不合法或当前不支持该 URL。请检查 `TaskItems[].Url` 的值。仅当 `SourceType` 取值为 `4` 时返回。 `UnsupportedSource`：`SourceType` 取值不正确。请检查 `SourceType` 的取值。 `ConvertRuleError`：规则参数校验失败，请检查 `SpecifiableRuleArgs` 参数中的规则配置是否正确。 `DBInsertFailed`：创建任务失败，请稍后重试。
ErrorMessage	String	`invalid video url`	创建失败的具体错误信息。

请求示例

POST https://livesaas.volcengineapi.com/?Action=CreateVideoTask&Version=2024-08-01
{
    "ProjectName": "1827*****8608457",
    "TaskName": "视频质检任务 A",
    "ScenarioId": 1,
    "SourceType": 3,
    "TaskItems": [
        {
            "SourceTaskId": 397***71
        }
    ],
    "CallbackURL": "https://callback.example.com/inspect",
    "Extra": "extra",
    "TagIds": [
        121
    ],
    "SpecifiableRuleArgs": [
        {
            "RuleId": 4005,
            "OcrScrollingSubtitlesArgs": {
                "PresetSubtitles": "最"
            }
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateVideoTask",
        "Version": "2024-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1"
    },
    "Result": {
        "TotalCount": 1,
        "SuccessCount": 1,
        "FailedCount": 0,
        "SuccessTasks": [
            {
                "Index": 0,
                "SourceId": "397***71",
                "TaskId": 397***71
            }
        ]
    }
}

错误码

下表提供了该接口特有的错误码，公共错误码请参见公共错误码和错误码文档。

状态码	错误码	错误信息	说明
400	TaskNameInvalidError	invalid task name	任务名称为空或长度超过限制。请检查 `TaskName` 的值。
400	ScenarioIdInvalidError	invalid scenario id	视频审核场景 ID 不存在或不属于当前项目。请检查 `ScenarioId` 的值。
400	CallbackURLInvalidError	invalid callback url	回调地址格式错误，仅支持 HTTP/HTTPS。请检查 `CallbackURL` 的值。
400	InvalidURL	invalid video url	视频 URL 为空、协议非法、指向 localhost 或内网地址，或无法通过安全校验。请检查 `TaskItems.Url` 的值。请传入公网可访问的视频的 URL。支持 HTTP/HTTPS 协议头。
400	UnsupportedVideoFormat	unsupported video format	暂不支持该视频格式。支持 MP4 或 M3U8 格式的视频。
403	TaskExceedLimitError	task exceeds limit	账号任务并发额度或时长包额度不足。
500	DBInsertFailed	db insert failed	创建任务失败。请稍后重试。

最近更新时间：2026.06.23 16:12:28

这个页面对您有帮助吗？

有用

无用

企业直播

注意事项 #

请求说明 #

请求参数 #

Query #

Body #

TaskItems #

SpecifiableRuleArgs #

OcrTextRecognitionArgs #

OcrScrollingSubtitlesArgs #

PresetScriptArgs #

返回参数 #

SuccessTasks #

FailedTasks #

请求示例 #

返回示例 #

错误码 #