UpdateCarouselTask - 更新轮播任务--视频直播-火山引擎

文档中心

立即注册

导航

UpdateCarouselTask - 更新轮播任务

最近更新时间：2025.04.09 11:15:30首次发布时间：2025.04.03 18:21:33

调用 UpdateCarouselTask 接口修改指定的轮播任务配置，调整播放内容、播放规则或时间范围，更新后系统将按新配置执行轮播任务。

注意事项

保持原配置：非必填参数不传时，将保持当前轮播任务的原有配置，不会恢复为默认值。
仅支持更新运行中任务：仅支持更新处于 running 状态的任务，您可调用 GetCarouselDetail 和 ListCarouselTask 接口查询任务状态。
请求频率：单用户请求频率限制为 10 次/秒。

请求说明

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

调试

API Explorer

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

去调试

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
TaskID	String	是	`44c5da50318440*********2d62c910b8`	待更新的轮播任务 ID，任务的唯一标识。调用 `CreateCarouselTask` 接口创建轮播任务时返回。
Rule	Object of Rule	是	`-`	轮播规则，用于指定轮播播放的素材和行为等。

Rule

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

参数	类型	是否必选	示例值	描述
Loop	Integer	否	`1`	指定此素材连续播放的次数。该字段值必须大于等于 `0`，不传时，将保持原有轮播配置。支持的取值及含义如下： `0`：不循环播放；其他正整数：按照指定次数循环播放。
Source	Array of Source	是	`-`	轮播素材列表，用于指定在轮播过程中播放的素材资源。
SeekInfo	Object of SeekInfo	否	`-`	控制素材更新后的播放行为的配置参数。

Loop

Integer

否

1

指定此素材连续播放的次数。该字段值必须大于等于 0，不传时，将保持原有轮播配置。支持的取值及含义如下：

0：不循环播放；
其他正整数：按照指定次数循环播放。

Source Array of Source 是 - 轮播素材列表，用于指定在轮播过程中播放的素材资源。

SeekInfo Object of SeekInfo 否 - 控制素材更新后的播放行为的配置参数。

Source

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

SeekInfo

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

参数	类型	是否必选	示例值	描述
Immediate	Long	否	`1`	用于设置素材切换的方式，默认值为 `0`。支持的取值及含义如下： `0`：播放完当前素材后，再进行素材的切换； `1`：立即切换到指定的素材，并按指定的播放进度开始播放。
SourceID	String	否	`1f9f207a55a43f45`	更新后播放的素材ID，只有在 `Immediate=1` 时才有效。如果不填，则直接从新素材的第一个素材开始播放。如果填了，则会从对应的 `SourceID` 开始播放。
SourceSeek	Long	否	`10`	切换素材后，素材播放的位置，单位为秒，表示从该位置开始播放，只有在 `Immediate=1` 时才有效。如果不填，表示从 `SourceID` 所对应素材的起始位置开始播放。

Immediate

Long

否

1

用于设置素材切换的方式，默认值为 0。支持的取值及含义如下：

0：播放完当前素材后，再进行素材的切换；
1：立即切换到指定的素材，并按指定的播放进度开始播放。

SourceID

String

否

1f9f207a55a43f45

更新后播放的素材ID，只有在 Immediate=1 时才有效。

如果不填，则直接从新素材的第一个素材开始播放。
如果填了，则会从对应的 SourceID 开始播放。

SourceSeek Long 否 10 切换素材后，素材播放的位置，单位为秒，表示从该位置开始播放，只有在 Immediate=1 时才有效。如果不填，表示从 SourceID 所对应素材的起始位置开始播放。

返回参数

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

参数	类型	示例值	描述
Data	Object of Data	`-`	包含任务更新相关信息的数据对象。

Data

参数	类型	示例值	描述
OptID	Integer	`2`	当前生效的任务配置序列号，用于标识最新的任务修改记录。每次任务配置更新后，该值会递增。

请求示例

POST https://live.volcengineapi.com?Action=UpdateCarouselTask&Version=2023-01-01
{
    "TaskID": "44c5da50318440*********2d62c910b8",
    "Rule": {
        "Loop": 1,
        "Source": [
            {
                "ID": "1",
                "Type": "vod",
                "Url": "https://live.example.com/video.mp4",
                "Seek": 10,
                "Loop": 1
            }
        ],
        "SeekInfo": {
            "Immediate": 1,
            "SourceID": "1f9f207a55a43f45",
            "SourceSeek": 10
        }
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestID": "202410301532184E885F20A2263C133082",
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateCarouselTask",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    },
    "Result": {
        "Data": {
            "OptID": 2
        }
    }
}

错误码

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

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