创建直播拉流任务

最近更新时间:2024-05-29 01:52:35

我的收藏

1. 接口描述

接口请求域名: live.tencentcloudapi.com 。

创建直播拉流任务。支持将外部已有的点播文件,或者直播源拉取过来转推到指定的目标地址。
注意:

  1. 默认支持任务数上限200个,如有特殊需求,可通过提单到售后进行评估增加上限。
  2. 源流视频编码目前只支持: H264, H265。其他编码格式建议先进行转码处理。
  3. 源流音频编码目前只支持: AAC。其他编码格式建议先进行转码处理。
  4. 可在控制台开启过期自动清理,避免过期任务占用任务数额度。
  5. 拉流转推功能为计费增值服务,计费规则详情可参见计费文档
  6. 拉流转推功能仅提供内容拉取与推送服务,请确保内容已获得授权并符合内容传播相关的法律法规。若内容有侵权或违规相关问题,云直播会停止相关的功能服务并保留追究法律责任的权利。

默认接口请求频率限制:50次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:CreateLivePullStreamTask。
Version String 公共参数,本接口取值:2018-08-01。
Region String 公共参数,详见产品支持的 地域列表
SourceType String 拉流源的类型:
PullLivePushLive -直播,
PullVodPushLive -点播,
PullPicPushLive -图片。
示例值:PullLivePushLive
SourceUrls.N Array of String 拉流源 url 列表。
SourceType 为直播(PullLivePushLive)只可以填1个,
SourceType 为点播(PullVodPushLive)可以填多个,上限30个。
当前支持的文件格式:flv,mp4,hls。
当前支持的拉流协议:http,https,rtmp,rtmps,rtsp,srt。
注意:
1. 建议优先使用 flv 文件,对于 mp4 未交织好的文件轮播推流易产生卡顿,可通过点播转码进行重新交织后再轮播。
2. 拒绝内网域名等攻击性拉流地址,如有使用,则做账号封禁处理。
3. 源文件请保持时间戳正常交织递增,避免因源文件异常影响推流及播放。
4. 视频编码格式仅支持: H264, H265。
5. 音频编码格式仅支持: AAC。
6. 点播源请使用小文件,尽量时长保持在1小时内,较大文件打开和续播耗时较久,耗时超过15秒会有无法正常转推风险。
7. 避免使用低频存储的文件,该类文件因低频存储,拉取时容易出现慢速,影响拉转推质量。
示例值:http://5000.liveplay.myqcloud.com/live/testsrc.flv?txSecret=4d8e
DomainName String 推流域名。
将拉取过来的流推到该域名。
注意:如果目标地址为非云直播,且样式不同于云直播,请使用 ToUrl 传入完整推流地址,详细用法请参考 ToUrl 参数说明。
示例值:5000.livepush.myqcloud.com
AppName String 推流路径。
将拉取过来的流推到该路径。
示例值:live
StreamName String 推流名称。
将拉取过来的流推到该流名称。
示例值:teststream
StartTime String 开始时间。
使用 UTC 格式时间,
例如:2019-01-08T10:00:00Z。
注意:北京时间值为 UTC 时间值 + 8 小时。
示例值:2021-02-07T08:00:00Z
EndTime String 结束时间,注意:
1. 结束时间必须大于开始时间;
2. 结束时间必须大于当前时间;
3. 结束时间 和 开始时间 间隔必须小于七天。
使用 UTC 格式时间,
例如:2019-01-08T10:00:00Z。
注意:北京时间值为 UTC 时间值 + 8 小时。
示例值:2021-02-09T08:00:00Z
Operator String 任务操作人备注。
示例值:admin
PushArgs String 推流参数。
推流时携带自定义参数。
示例:
bak=1&test=2 。
CallbackEvents.N Array of String 选择需要回调的事件(不填则回调全部):
TaskStart:任务启动回调,
TaskExit:任务停止回调,
VodSourceFileStart:从点播源文件开始拉流回调,
VodSourceFileFinish:从点播源文件拉流结束回调,
ResetTaskConfig:任务更新回调。

TaskAlarm: 用于告警事件通知,AlarmType 示例:
PullFileUnstable - 文件拉取不稳定,
PushStreamUnstable - 推流不稳定,
PullFileFailed - 文件拉取出错,
PushStreamFailed - 推流出现失败,
FileEndEarly - 文件提前结束。
VodLoopTimes String 点播拉流转推循环次数。默认:-1。
-1:无限循环,直到任务结束。
0:不循环。
>0:具体循环次数。次数和时间以先结束的为准。
注意:该配置仅对拉流源为点播时生效。
示例值:-1
VodRefreshType String 点播更新SourceUrls后的播放方式:
ImmediateNewSource:立即播放新的拉流源内容;
ContinueBreakPoint:播放完当前正在播放的点播 url 后再使用新的拉流源播放。(旧拉流源未播放的点播 url 不会再播放)

注意:该配置生效仅对变更前拉流源为点播时生效。
示例值:ContinueBreakPoint
CallbackUrl String 自定义回调地址。
拉流转推任务相关事件会回调到该地址。
回调事件使用方法请查看:
https://cloud.tencent.com/document/product/267/32744
https://cloud.tencent.com/document/product/267/56208
ExtraCmd String 其他参数。
示例: ignore_region 用于忽略传入地域, 内部按负载分配。
SpecifyTaskId String 自定义任务 ID。
注:
1. 该自定义 ID 为可选参数,如果传入,请确保该账号下传入的 ID 唯一。
2. 该自定义 ID 用于防止重复发起请求时产生重复任务。后面也可以用 SpecifyTaskId 来修改或删除任务。
Comment String 任务描述,限制 512 字节。
示例值:任务描述
ToUrl String 完整目标 URL 地址。
用法注意:如果使用该参数来传完整目标地址,则 DomainName, AppName, StreamName 需要传入空字符串,任务将会使用该 ToUrl 参数指定的目标地址。

使用该方式传入目标地址支持的协议有:
rtmp、rtmps、rtsp、rtp、srt。

注意:签名时间需要超过任务结束时间,避免因签名过期造成任务失败。
BackupSourceType String 备源的类型:
PullLivePushLive -直播,
PullVodPushLive -点播。
注意:
1. 仅当主源类型为直播源时,备源才会生效。
2. 主直播源拉流中断时,自动使用备源进行拉流。
3. 如果备源为点播文件时,则每次轮播完点播文件就检查主源是否恢复,如果主源恢复则自动切回到主源,否则继续拉备源。
示例值:PullLivePushLive
BackupSourceUrl String 备源 URL。
只允许填一个备源 URL
示例值:http://5000.liveplay.myqcloud.com/live/backup.flv?txSecret=4d8e
WatermarkList.N Array of PullPushWatermarkInfo 水印信息列表。
注意:
1. 最多支持4个不同位置的水印。
2. 水印图片 URL 请使用合法外网可访问地址。
3. 支持的水印图片格式:png,jpg,gif 等。
VodLocalMode Integer 点播源是否启用本地推流模式,默认0,不启用。
0 - 不启用。
1 - 启用。
注意:启用本地模式后,会将源列表中的 MP4 文件进行本地下载,优先使用本地已下载文件进行推流,提高点播源推流稳定性。使用本地下载文件推流时,会产生增值费用。
示例值:0
RecordTemplateId String 录制模板 ID。
BackupToUrl String 新的目标地址,用于任务同时推两路场景。
TranscodeTemplateName String 直播转码模板,使用云直播的转码功能进行转码后再转推出去。转码模板需在云直播控制台创建。
示例值:hevc720

3. 输出参数

参数名称 类型 描述
TaskId String 任务 Id 。
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 请求示例

用于创建直播拉流任务。

输入示例

POST / HTTP/1.1
Host: live.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateLivePullStreamTask
<公共请求参数>

{
    "SourceType": "PullLivePushLive",
    "DomainName": "5000.livepush.myqcloud.com",
    "SourceUrls": [
        "rtmp://5000.liveplay.myqcloud.com/live/stream1"
    ],
    "StreamName": "test",
    "AppName": "live",
    "StartTime": "2019-12-16T11:02:00Z",
    "Operator": "vinson",
    "EndTime": "2019-12-17T12:02:00Z"
}

输出示例

{
    "Response": {
        "TaskId": "10000",
        "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码 描述
FailedOperation 操作失败。
FailedOperation.CallOtherSvrFailed 调用内部服务失败。
InvalidParameter 参数错误。
InvalidParameter.InvalidBackupToUrl 无效的备用推流地址。
InvalidParameter.InvalidCallbackUrl 回调地址不规范。
InvalidParameter.InvalidMixInputParam 混流输入参数无效。
InvalidParameter.InvalidOutputParam 输出流参数无效。
InvalidParameter.InvalidSourceUrl 源地址不规范。
InvalidParameter.InvalidTaskTime 任务时间超出限制。
InvalidParameter.InvalidToUrl 目标地址不规范。
InvalidParameter.InvalidWatermark 水印参数有误。
InvalidParameter.TaskNotExist 任务不存在。
InvalidParameter.TaskNumMoreThanLimit 任务数超过限制。
InvalidParameter.ToUrlNoPermission 外部地址无权限。
InvalidParameterValue 参数取值错误。
ResourceNotFound.ForbidService 用户被禁用。
ResourceNotFound.FreezeService 用户服务被冻结。
ResourceNotFound.StopService 账号停服,请先冲正开通服务后再操作。
ResourceNotFound.UserDisableService 用户主动停服。
ResourceNotFound.UserNotExist 用户未注册直播。