You need to enable JavaScript to run this app.
导航
视频直播
  • 文档首页
    • /视频直播/API 参考/云端混流/创建云端混流任务
创建云端混流任务
最近更新时间：2024.09.20 11:27:27首次发布时间：2024.06.24 10:59:27
我的收藏

调用 CreateCloudMixTask 接口，创建云端混流任务，支持将直播流、点播视频和图片等输入源重新布局混流后推送到指定推流地址。

注意事项

  • 计费说明：云端混流为收费功能，费用详细说明请参考混流计费。
  • 请求频率：单用户请求频率限制为 10 次/秒。
  • 生效时间：混流任务创建 5 -10s 后直播素材可以拉流观看。
  • 使用限制：云端混流任务最长持续 3 天，单个输入源断流后保留最后一帧进行展示，全部输入源断流 1 分钟后混流任务自动结束。

请求说明

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

调试

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

请求参数

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

Query

参数类型是否必选示例值描述
ActionString是CreateCloudMixTask接口名称。当前 API 的名称为 CreateCloudMixTask。
VersionString是2023-01-01接口版本。当前 API 的版本为 2023-01-01。

Body

参数类型是否必选示例值描述
NameString是mixtask001混流任务名称，与正在进行中的任务名称不能重复。
MixedRulesObject of MixedRules是-混流任务详细配置。

MixedRules

参数类型是否必选示例值描述
InputSourceArray of InputSource是-混流素材列表，最多支持配置 8 路素材。
InputLayoutObject of InputLayout是-混流输出布局配置。
OutputObject of Output是-混流输出视频质量参数配置。

InputSource

参数类型是否必选示例值描述
IDString是1混流素材 ID，一个任务中素材 ID 不能重复，此 ID 用于任务状态回调消息中标识素材。

Layer

Integer

是

1

混流素材的叠放顺序，1 为最底层，2 层在 1 层之上，以此类推，取值范围为[1,9999]。

说明

当前准备使用某个素材作为布局背景时，其叠放顺序应设置为所有素材中的最小值。

Type

String

是

vod

混流素材类型，支持的取值及含义如下所示。

  • vod：视频点播中的素材，支持 MP4、FLV 格式素材；
  • live：直播源素材，支持 RTMP、FLV 协议拉流地址；
  • pic：图片素材，支持 png、jpg 格式图片。

Url

String

是

https://tos.example.org/obj/test.mp4

混流素材的访问地址。

说明

混流素材的访问地址需与混流素材的类型保持对应关系。

InputLayout

参数类型是否必选示例值描述
SceneObject of Scene是-混流输出画布配置及素材布局配置。

Logo

Array of Logo

否

-

混流输出视频中 Logo 布局配置。

说明

支持最多配置 4 个 Logo，展示层级以添加顺序为准。

Output

参数类型是否必选示例值描述
VideoObject of Video是-混流视频参数设置。
AudioObject of Audio是-混流音频参数设置。
UrlArray of String是["push.example.com","push2.example.com"]混流视频的推流地址，支持最多配置 8 个推流地址。
CallbackObject of Callback否-任务状态回调地址配置。

Scene

参数类型是否必选示例值描述
HeightInteger是1080混流输出整体画布高度，单位为 px，取值范围为 [10,2160]。
WidthInteger是1920混流输出画布整体宽度，单位为 px，取值范围为 [10,2160]。

Layout

Array of Layout

是

-

混流素材在混流输出整体画面中的布局配置。

说明

混流素材布局中需包含所有素材的配置，且需与通过 Layer 参数与混流素材一一匹配。

参数类型是否必选示例值描述
UrlString是http://tos.example.org/obj/test/logo001.pngLogo 图片访问地址。
LayoutObject of Layout是-Logo 图片在混流输出整体画面中的布局配置。

Video

参数类型是否必选示例值描述
BitRateInteger是8000000混流输出视频码率，单位为 bps，取值范围为 [1000000,20000000]，输入值小于或大于取值范围时会进行自动修正至最小值和最大值。
FrameRateInteger是30混流输出视频帧率，单位为 fps，取值范围为 [10,60]，输入值小于或大于取值范围时会进行自动修正至最小值和最大值。
GOPInteger是2IDR 帧之间的最大间隔时间，单位为秒，取值范围为 [1,10]。

Codec

String

是

h264

混流输出视频编码格式，支持的取值及含义如下所示。

  • h264：使用 H.264 编码格式；
  • h265：使用 H.265 编码格式。

Audio

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

BitRate

Integer

是

320000

混流输出流的音频码率，单位为 bps，取值范围为 [128000,320000]，常见取值及含义如下所示。

  • 128000：128 kbps；
  • 144000：144 kbps；
  • 256000：256 kbps；
  • 320000：320 kbps。

ChannelLayout

String

是

stereo

混流输出流的音频声道设置，取值及含义如下所示。

  • mono：单声道；
  • stereo：立体声。

SampleRate

Integer

是

48000

混流输出流的音频采样率，单位为 HZ，常见取值及含义如下所示。

  • 32000：32 kHZ；
  • 44100：44.1 kHZ；
  • 48000：48 kHZ。

Callback

参数类型是否必选示例值描述
UrlString是https://callback.com接收云端混流任务状态回调的 HTTP 地址。

Layout

参数类型是否必选示例值描述
XInteger是0当前素材或 Logo 图片在输出画面中相对画面左上角的 X 偏移位置，单位为 px，取值范围为 0 到设置的画面宽度。
YInteger是0当前素材或 Logo 图片在输出画面中相对画面左上角的 Y 偏移位置，单位为 px，取值范围为 0 到设置的画面高度。
WInteger是960当前素材或 Logo 图片在混流输出画面中的限制宽度，单位为 px，取值范围为 [10,2160]。

H

Integer

是

540

当前素材或 Logo 图片在混流输出画面中的限制高度，单位为 px，取值范围为 [10,2160]。

说明

限制宽度和限制高度指定了素材展示的限制范围，当素材尺寸和限制值不一致时，素材将在限制范围内根据长边进行等比缩放，其余区域透明展示。

Layer

Integer

是

1

当配置素材布局时需要通过 Layer 参数与素材进行一一对应。

说明

配置 Logo 图片的布局时此参数不生效。

返回参数

本接口无特有的返回参数。更多信息请见返回结构。

参数类型示例值描述

Code

Integer

0

请求响应码，取值及含义如下。

  • 0：请求成功；
  • 500：内部处理错误；
  • 400：请求异常。
MessageStringsuccess请求响应码对应的信息。
DataObject of Data-返回的数据。

Data

参数类型示例值描述
TaskIDString1237813323442混流任务 ID。

请求示例

POST https://live.volcengineapi.com?Action=CreateCloudMixTask&Version=2023-01-01
{
    "Name": "mixtask001",
    "MixedRules": {
        "InputLayout": {
            "Scene": {
                "Height": 1080,
                "Width": 1920,
                "Layout": [
                    {
                        "X": 0,
                        "Y": 0,
                        "W": 960,
                        "H": 540,
                        "Layer": 1
                    }
                ]
            },
            "TemplateID": "如切经",
            "Logo": [
                {
                    "Layout": {
                        "X": 0,
                        "Y": 0,
                        "W": 200,
                        "H": 200
                    },
                    "Url": "http://tos.example.org/obj/test/logo001.png"
                }
            ]
        },
        "Output": {
            "Audio": {
                "BitRate": 320000,
                "ChannelLayout": "stereo",
                "SampleRate": 48000
            },
            "Url": [
                "push.example.com",
                "push2.example.com"
            ],
            "Video": {
                "BitRate": 8000000,
                "FrameRate": 30,
                "GOP": 2
            },
            "Callback": {
                "Url": "指适市原部"
            }
        },
        "InputSource": [
            {
                "ID": "1",
                "Layer": 1,
                "Type": "vod",
                "Url": "https://tos.example.org/obj/test.mp4"
            }
        ]
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateCloudMixTask",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    },
    "Result": {
        "Code": 0,
        "Message": "success",
        "Data": {
            "TaskID": "123781abc3323442"
        }
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。