帮你快速理解、总结文档立即下载
文档中心>实践教程>媒体处理>直播录制接入>直播间录制接入

直播间录制接入

最近更新时间：2026-09-04 10:29:02
我的收藏

本页目录：

功能介绍

直播间录制是媒体处理 MPS 媒体 AI 提供的一项录制能力。您只需提供直播间的页面 URL，MPS 会自动进入该直播间、拉取画面并完成录制，录制生成的 MP4 文件直接存储到您指定的 COS 存储桶中。
与传统的 直播流录制 不同，本功能不要求您预先获取 RTMP/HLS/FLV 等拉流地址，也不需要创建录制模板和直播编排，输入直播间 URL 即可发起录制。

计费说明

直播间录制按录制时长计费。详细定价请参考 按量计费 文档。
录制产生的视频文件存储在您自己的 COS 存储桶中，相应的存储和流量费用由 COS 按其计费规则单独收取。

前提条件

在使用本功能前，您需完成以下前置操作：
1. 注册并登录腾讯云账号，开通 MPS 产品，完成服务角色授权。 具体指引请参考 快速入门，账号授权相关问题可参考 账号授权 文档。若您使用腾讯云子账号，还需保证该账号有足够权限使用 MPS 产品。
2. 开通对象存储 COS 并创建存储桶。 录制结果文件需要写入您的 COS 桶，请提前创建好存储桶并记录桶名称与所属地域。
说明：
创建并授权 MPS_QcsRole 角色。 该角色用于授权 MPS 将录制文件写入您的 COS 桶，未完成授权会导致任务在结果上传阶段失败。可参考 账号授权相关 文档。

接入流程

整体链路分为两步：
1. 调用 CreateAgentRecordTask 创建录制任务，获取 TaskId。
2. 使用 TaskId 轮询调用 DescribeAgentRecordTask 查询任务进度，任务成功后从返回结果中获取录制文件 URL。
接口请求域名均为 mps.tencentcloudapi.com，接口版本为 2019-06-12，默认请求频率限制为20次/秒。本组接口不需要传递 Region 公共参数。
建议先通过 API Explorer 完成快速验证，填写参数后即可在线发起调用，并自动生成各语言 SDK 代码：
CreateAgentRecordTask 在线调试
DescribeAgentRecordTask 在线调试

发起直播间录制任务

调用 CreateAgentRecordTask 接口创建录制任务。

请求参数说明

是
参数名称
必选
类型
描述
LiveRoomUrl
是
String
直播间 URL。
MaxDurationMinutes
是
Integer
最长录制时长，单位为分钟，最长支持720分钟。
StoreCosParam
是
AgentStoreCosParam
结果文件存储的 COS 桶信息。注意：需开通 COS，并创建、授权 MPS_QcsRole 角色。
StartTime
否
String
定时录制开始时刻，格式为 2026-07-01T15:31:32+08:00。留空表示提交后立即开始录制；非空表示从该时刻开始录制。
InterruptPolicy
否
String
中断策略，取值 STOP_ON_INTERRUPT（直播流中断后立即结束录制）或 CONTINUE_UNTIL_END（忽略中断，继续录制直到任务结束时间）。默认值为 STOP_ON_INTERRUPT。
其中 StoreCosParam 为 AgentStoreCosParam 结构：
字段名
类型
描述
CosBucketName
String
存储至 COS 的存储桶名称，需要 COS 存储时必填。
CosBucketRegion
String
存储桶所属地域，需与存储桶实际地域一致，上传 COS 时必填。
CosBucketPath
String
存储至 COS 的路径，可选。

关键参数使用建议

MaxDurationMinutes 该填多少。 该参数是录制时长的硬上限，录制到该时长即结束任务。若直播时长不可预估，建议按预计时长上浮一定余量填写；若直播提前结束且中断策略为 STOP_ON_INTERRUPT，任务会随直播中断而提前结束，不会无意义地占满设定时长。单个任务最长不超过720分钟，超长直播需拆成多个任务分段录制。
StartTime 与 MaxDurationMinutes 的关系。 录制的结束时刻由 StartTime + MaxDurationMinutes 决定。使用定时录制时，建议将 StartTime 设置为略早于计划开播时间，避免因开播提前而漏录开头内容。
中断策略如何选择。 若直播链路稳定、且希望直播一结束就拿到文件，使用默认的 STOP_ON_INTERRUPT；若主播网络存在抖动、中途可能短暂断流，但您希望拿到一份完整的录制内容，则使用 CONTINUE_UNTIL_END，此时任务会一直持续到 MaxDurationMinutes 耗尽为止。

请求示例

示例一：立即开始录制

POST / HTTP/1.1
Host: mps.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAgentRecordTask
{
    "LiveRoomUrl": "https://****.******.com/***********",
    "MaxDurationMinutes": 60,
    "StoreCosParam": {
        "CosBucketName": "******-test-live-record-task-**********",
        "CosBucketRegion": "ap-guangzhou",
        "CosBucketPath": "record-only"
    }
}
响应示例：
{
    "Response": {
        "TaskId": "task_9fac9a28f27292d8fbdf26e63beaeb03",
        "RequestId": "8a3e4c65-b473-456f-9158-57f3b0a5aff6"
    }
}

示例二：定时开始录制

在立即录制的基础上补充 StartTime，并按需指定中断策略：
{
    "LiveRoomUrl": "https://****.******.com/***********",
    "MaxDurationMinutes": 120,
    "StoreCosParam": {
        "CosBucketName": "******-test-live-record-task-**********",
        "CosBucketRegion": "ap-guangzhou",
        "CosBucketPath": "record-only"
    },
    "StartTime": "2026-07-03T12:10:28+08:00",
    "InterruptPolicy": "CONTINUE_UNTIL_END"
}
响应示例：
{
    "Response": {
        "TaskId": "task_857a704be0d4da429630928dc35f8b33",
        "RequestId": "7bf98ed1-4e2b-4be6-ab54-ae0f4d1e502d"
    }
}

查询任务结果

调用 DescribeAgentRecordTask 接口，传入创建任务时返回的 TaskId，查询任务进度并获取录制结果。

请求示例

POST / HTTP/1.1
Host: mps.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeAgentRecordTask
{
    "TaskId": "240****2-MllmVideoTest-9baf86edd37b1491037414981e556bf0"
}
响应示例：
{
    "Response": {
        "Status": "SUCCESS",
        "RecordUrls": [
            "https://***********-live-record-task-**********.cos.ap-guangzhou.myqcloud.com/record-only/240****2-MllmVideoTest-7fedc0fb7c4fc718fd9792ca8e04e80f-2026-07-15-12-04-29.mp4"
        ],
        "RequestId": "092b9f39-6bbd-4d34-b9aa-b5693f639edf"
    }
}

输出参数说明

参数名称
类型
描述
Status
String
任务当前状态，取值 WAITING（等待中）、RUNNING（执行中）、SUCCESS（成功）、FAILED（失败）。
ErrorMessage
String
当任务状态为 FAILED 时，返回失败信息。
RecordUrls
Array of String
当任务状态为 SUCCESS 时，返回录制文件 URL 列表。
RequestId
String
唯一请求 ID，定位问题时需提供。

状态流转与轮询建议

任务提交后进入 WAITING，等待到达录制开始时刻；开始录制后转为 RUNNING；录制结束并完成文件上传 COS 后转为 SUCCESS，此时 RecordUrls 才会返回可用的录制文件地址。
业务侧处理逻辑建议如下：
只在 SUCCESS 时取文件。 任务处于 RUNNING 时不应认为录制文件已可用，请以 Status 为准判断，而不是以 RecordUrls 字段是否存在为准。
合理设置轮询间隔。 录制类任务耗时较长（等待开播 + 录制时长），无需高频轮询。建议对定时任务在预计开始时刻前后再启动轮询，录制期间按分钟级间隔查询，接口默认频率限制为20次/秒，请避免无意义的密集调用。
失败时记录 ErrorMessage 与 RequestId。 例如 copy to bucket failed: copy object failed 一类的错误通常指向 COS 配置或角色授权问题，携带 RequestId 提工单可快速定位。

录制结果文件

录制结果为 MP4 文件，存放在您创建任务时指定的 COS 桶及路径下，文件名包含任务标识与录制起始时间，可直接用于后续的转码、AI 分析或分发。

常见问题与注意事项

直播间 URL 填写错误或直播间不可访问会怎样

请确保提交的直播间 URL 可正常公开访问。若 MPS 无法进入直播间或无法获取到画面，任务将返回 FAILED，并在 ErrorMessage 中给出失败原因。建议在正式接入前，先用一条短时长（如 MaxDurationMinutes 设为 1）的任务验证链路连通性，再投入正式录制。

录制文件没有出现在 COS 桶里

请依次检查：CosBucketName 与 CosBucketRegion 是否与存储桶实际信息一致（地域填错是最常见的原因）；是否已创建并授权 MPS_QcsRole 角色；该账号对目标存储桶是否具备写入权限。

能否录制超过720分钟的直播

单任务上限为720分钟。如需覆盖更长时间的直播，请拆分为多个任务，通过 StartTime 首尾衔接，业务侧再对多个 MP4 文件进行拼接处理。

定时任务提交后能否修改

接口暂不支持修改已提交任务的参数。若录制计划发生变化，请重新提交一个新任务并按新参数录制。

任务的错误码

创建任务接口的业务错误码包括 InternalError（内部错误）、InvalidParameter（参数错误）、MissingParameter（缺少参数错误）；查询任务接口的业务错误码包括 InternalError、MissingParameter、ResourceNotFound（资源不存在）。其他错误码详见 公共错误码。

相关文档

创建 Agent 录制任务（CreateAgentRecordTask）
查询 Agent 录制任务（DescribeAgentRecordTask）
按量计费
快速入门
账号授权

中国站