CreateCarouselTask - 创建轮播任务--视频直播-火山引擎

文档中心

立即注册

导航

CreateCarouselTask - 创建轮播任务

最近更新时间：2025.04.22 20:43:41首次发布时间：2025.04.03 18:21:33

调用 CreateCarouselTask 接口创建一个轮播任务，在直播过程中，视频直播服务端将根据任务配置按设定顺序循环播放指定视频内容。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。

请求说明

请求方式：POST
请求地址：https://live.volcengineapi.com?Action=CreateCarouselTask&Version=2023-01-01

调试

API Explorer

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

去调试

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
Name	String	是	`商品轮播`	轮播任务的名称，用于标识任务。支持由中文、大小写字母（A - Z、a - z）和数字（0 - 9）组成。说明此名称不能与其他正在运行中的任务名称重复。启动的任务不允许使用重复的名称。
Rule	Object of Rule	是	`-`	轮播规则，用于指定轮播播放的素材和行为等。

Rule

参数	类型	是否必选	示例值	描述
Loop	Integer	是	`-1`	轮播的循环次数，用于控制直播循环播放的次数。支持的取值及含义如下： `-1`：无限循环； `0`：不循环；其他正整数：指定轮播的具体循环次数。说明直播循环的行为同时受到 `Loop` 和 `StopTime` 字段的影响：当 `Loop` 次数达到设定值时，轮播将自动停止，无论 `StopTime` 是否到达。当 `StopTime` 到达时，轮播也会终止，即使 `Loop` 仍未完成。如果未设置 `StopTime`，系统默认最大轮播时长为 3 天。
Mode	Integer	是	`1`	该字段用于指定轮播素材的拼接模式，决定多个点播素材在播放时的衔接方式，支持的取值如下所示： `0`：普通模式。会检查前后素材的音视频参数（如分辨率、码率、编码格式等）。如果参数匹配，素材可以无缝衔接；如果参数不同，切换时可能会出现短暂的断流情况。 `1` ：转码模式。系统会对所有点播素材进行格式化处理，使其符合相同的音视频参数，确保素材切换时始终保持流畅无缝衔接。用户可以手动配置目标参数，如果未配置，默认使用第一个素材的参数。
Output	Object of Output	是	`-`	轮播任务的推流参数，包括视频、音频、推流地址及回调信息。
PlayTime	Integer	否	`1672531200000`	轮播任务的开始时间，使用 Unix 时间戳表示，精度为 `ms`。参数要求如下：当取值为 `0` 时，表示立即开始推流；如果设置具体时间，则必须为晚于当前时间的值。
StopTime	Integer	否	`1672800000000`	轮播任务的停止时间，Unix 时间戳，精度为 `ms`。设置此字段后，系统会根据该时间点自动关闭任务。最大时间范围为 `3天`，默认值为 `3天`。说明轮播任务的结束时间 `StopTime` 必须晚于开始时间 `PlayTime`。
Source	Array of Source	是	`-`	轮播素材列表，用于指定在轮播过程中播放的素材资源。

Output

参数	类型	是否必选	示例值	描述
Video	Object of Video	否	`-`	在转码模式（即 `Rule.Mode = 1`）下生效，可选择配置推流的视频参数。缺省情况下，所有参数（除 GOP 外）均按照第一个素材的设置进行轮播处理。
Audio	Object of Audio	否	`-`	在转码模式（即 `Rule.Mode = 1`）下生效，可用于配置推流的音频参数。
Url	Array of String	是	`[ "rtmp://push.example.com/live/stream1" ]`	推流的 RTMP 或 RTMPS 地址，支持多推（即同时向多个推流地址推送相同的直播内容）。地址条数最少为 1 条，最多支持 8 条
Callback	Object of Callback	否	`-`	回调函数配置，以便接收任务状态更新等通知。

Source

参数	类型	是否必选	示例值	描述
ID	String	是	`1`	轮播素材的唯一标识符。在同一播放列表中，每个素材的 `ID` 必须唯一，不允许重复。
Type	String	是	`vod`	轮播素材的文件类型，用于指定素材的文件来源类型。支持以下取值： `vod`：点播 MP4 或 FLV 文件； `m3u8`：点播 M3U8 文件。
Url	String	是	`https://live.example.com/video.mp4`	轮播素材的公网可访问地址。确保提供的地址能够被公网正常访问，以便正确加载轮播素材内容。
Loop	Integer	否	`1`	指定此素材连续播放的次数。该字段值必须大于等于 `0`，默认值为 `0`。支持的取值及含义如下： `0`：不循环播放；其他正整数：按照指定次数循环播放。
Seek	Integer	否	`10`	用于控制当前素材播放时跳过开头的一段时间，例如，跳过片头，单位为秒。该字段仅在素材类型为视频点播（`type=vod`）时有效。以下是该字段的使用规则：如果 `Seek` 的取值小于等于 `0` 或大于视频的实际时长，则该字段不生效。确保根据点播素材的实际长度设置合适的值，以实现跳过片头的效果。

Video

参数	类型	是否必选	示例值	描述
BitRate	Integer	否	`15`	视频的码率，单位为 `bit`，取值必须小于或等于 `20`。如果指定了 `Video` 对象，则该字段为必填项。
FrameRate	Integer	否	`30`	视频帧率，取值范围为 `[10, 60]`。如果指定了 `Video` 对象，则该字段为必填项。
GOP	Integer	否	`5`	IDR 帧之间的最大间隔，单位为秒，默认值为 `2`，取值范围为 `[1,10]`。
Width	Integer	否	`1920`	视频宽度，单位为像素。支持的取值范围为 `[10, 2160]`。如果指定了 `Video` 对象，则该字段为必填项。
Height	Integer	否	`1080`	视频的高度（单位：像素），取值范围为 `[10, 2160]`。如果指定了 `Video` 对象，则该字段为必填项。

Audio

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

BitRate Integer 否 320000 音频码率的设置范围，支持的取值为 [128000, 640000]，单位为 bps。如果指定了 Audio 对象，则该字段为必填项。

参数	类型	是否必选	示例值	描述
BitRate	Integer	否	`320000`	音频码率的设置范围，支持的取值为 `[128000, 640000]`，单位为 `bps`。如果指定了 `Audio` 对象，则该字段为必填项。
ChannelLayout	String	否	`stereo`	音频的声道布局，如果指定了 `Audio` 对象，则该字段为必填项。支持以下取值： `mono`：单声道。 `stereo`：双声道。
SampleRate	Integer	否	`48000`	音频的采样率参数，如果指定了 `Audio` 对象，则该字段为必填项。支持的采样率值包括： `22000` `32000` `44100` `48000` 请选择适合您的业务需求的采样率进行配置。

ChannelLayout

String

否

stereo

音频的声道布局，如果指定了 Audio 对象，则该字段为必填项。支持以下取值：

mono：单声道。
stereo：双声道。

SampleRate

Integer

否

48000

音频的采样率参数，如果指定了 Audio 对象，则该字段为必填项。支持的采样率值包括：

22000
32000
44100
48000
请选择适合您的业务需求的采样率进行配置。

Callback

参数	类型	是否必选	示例值	描述
Url	String	是	`https://callback.example.com/notify`	回调地址。该字段需准确配置，用于接收系统回调信息。

返回参数

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

参数	类型	示例值	描述
Data	Object of Data	`-`	轮播任务数据对象。

Data

参数	类型	示例值	描述
TaskID	String	`e1fb009334fc5b16`	轮播任务的唯一标识。

请求示例

POST https://live.volcengineapi.com?Action=CreateCarouselTask&Version=2023-01-01
{
    "Name": "轮播测试",
    "Rule": {
        "Loop": -1,
        "Mode": 1,
        "Output": {
            "Url": [
                "rtmp://push.example.com/live/stream1"
            ]
        },
        "Source": [
            {
                "ID": "1",
                "Type": "vod",
                "Url": "https://live.example.com/video.mp4"
            }
        ]
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestID": "202410301432037DE157BFBC968410056C",
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateCarouselTask",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    },
    "Result": {
        "Data": {
            "TaskID": "e1fb009334fc5b16"
        }
    }
}

错误码

下表仅列出本接口特有的错误码。更多信息请参见公共错误码获取详细信息。

状态码	错误码	错误信息	说明
400	InvalidParam	-	输入的参数无效或不符合要求，请参照请求参数说明进行检查。
500	InternalError	an internal error occurred, please contact the administrator.	出现内部错误，请联系技术支持。