Live Ingest & Forwarding

当您的源视频无法直接推流到我们的网络时，Live Ingest & Forwarding（直播流接入与转推）功能可帮助您从任意外部源接入视频，并将其分发到一个或多个目标。作为强大的流中继，该功能为无法直接发布的场景提供了基于API的解决方案。

该流程包含两个主要操作步骤：

• 拉流（Pull）：我们的服务可通过"拉流"方式主动从您提供的源URL接入实时视频流。
• 转推（Push）：接入的流将被再次推流到您指定的一个或多个RTMP目标URL，实现内容向其他平台或CDN的分发。

鉴权

所有高级接口请求都必须通过在端点URL后附加三个查询参数 n、r 和 k 进行认证。

• n：您的CDNetworks平台帐户名称。
• r：唯一的随机字符串（最大32个字符），建议使用Unix时间戳。
• k：32位MD5签名。

MD5签名计算方式

签名参数 k 的计算方式为 md5(r + key)，其中 key 为您的API密钥。

1. 获取您的密钥：请联系 CDNetworks 客服获取您的密钥（key）。
2. 生成随机字符串：为 r 创建一个唯一的字符串。例如：r = 1409284800。
3. 拼接字符串：将您的密钥追加到随机字符串之后。
   • 如果 key = 012f37a3f2952，则组合后的字符串为 1409284800012f37a3f2952。
4. 计算 MD5 哈希值：对组合后的字符串进行 MD5 哈希计算，得到 k。
   • k = md5("1409284800012f37a3f2952") 计算结果为 b9fed80be752551834eec3e52fa94115。

任务管理

该功能可以通过以下两种方式进行控制：

• 实时任务：对正在直播中的流立即启动或停止转推。
• 定时任务：为尚未开始的流预设置具体的开始与结束时间。

该接口用于创建、停止、更新及恢复直播转推任务。

• HTTP 方法: POST
• 接口地址: http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action
• 请求头: Content-Type: application/json

示例请求URL：

http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action?n=your_account&r=1409284800&k=b9fed80be752551834eec3e52fa94115

示例请求体（cmd=1，创建任务）：

{
"transcallbackurl": "http://example.com/api/callback",
"cmd": "1",
"type": "live",
"list": [
{
"id": "task_unique_id_001",
"src": [
{
                    "url": "http://source.example.com/live/stream1.flv",
                    "wmImage": "http://source.example.com/assets/logo.jpg",
                    "wmGravity": "TOP_LEFT"
                },
                {
                    "url": "http://backup.example.com/live/stream1.flv"
                }
            ],
            "forward": [
                {
"url": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)"
},
{
"url": "rtmp://[dest2.example.com/live/output](https://dest2.example.com/live/output)"
}
],
"start": "1495177025000",
"end": "1495184225000",
"fops": {
"bps": "1200000",
                "res": "1280x720",
                "fps": "25",
                "vcodec": "libx264",
                "forced_gopInterval": "3000"
            },
            "extendParam": {
                "waitCrtUrlFinish": "1"
            }
        }
    ]
}

请求体参数

字段	类型	是否必填	说明
transcallbackurl	String	否	用于接收状态和事件通知（回调）的URL。
cmd	String	是	执行的命令： 1：创建并启动任务。 2：停止任务。 3：更新正在运行任务的源列表。 5：恢复已停止的任务。
type	String	是	内容的类型。live 表示直播流，video 表示点播文件（VOD）。
list	Array	是	任务对象的数组。详见下文。

list 对象参数

字段	类型	必填	说明
id	String	是	任务的唯一标识符（最多32个字符）。若提交新任务的id与现有任务相同，则旧任务会被停止。
src	Array	是	源流对象的数组。详见下文。
forward	Array	是	目标转推对象的数组。详见下文。
start	String	否	计划开始时间（13位Unix时间戳，单位毫秒）。如无此项，任务立即开始。
end	String	否	计划结束时间（13位Unix时间戳，单位毫秒）。在此时间点任务会自动停止。
fops	Object	否	转码和编码设置。详见下文。
extendParam	Object	否	用于细粒度调整任务行为的高级参数。详见下文。

src 对象参数

字段	类型	必填	描述
url	String	是	拉流源地址。可配置多个URL以实现冗余。支持的格式包括： 直播协议：RTMP、HLS（.m3u8）、HTTP-FLV、RTSP 视频格式：MP4、FLV、HLS（.m3u8）
wmImage	String	否	水印图片的 URL。如有多个水印，请用分号（;）分隔。 注意： 若 URL 中包含 & 等特殊字符，需进行 URL 编码。
wmGravity	String	否	水印的静态位置。默认值为 TOP_RIGHT。可选值包括：TOP_LEFT、TOP_CENTER、TOP_RIGHT、CENTER_LEFT、CENTER、CENTER_RIGHT、BOTTOM_LEFT、BOTTOM_CENTER、BOTTOM_RIGHT。
wmPosition	String	否	指定水印左上角的位置，使用视频宽高的百分比作为单位。格式为 WxH%，其中 W 表示距离视频左边缘的百分比，H 表示距离视频上边缘的百分比。 例如，30%x40% 表示水印的起始点位于距离视频左侧 30% 宽度、距离顶部 40% 高度的位置。取值范围为 0 到 99 的整数。 该参数与 wmGravity 互斥，如同时设置，定位行为可能不可预测。
relofftime	String	否	指定任务的相对时间片段，单位为秒。行为取决于流的 type： 点播（type=video）：格式为 [start_second]-[end_second]。用于定义源文件内的具体片段，例如 30-60 表示使用视频 30 秒到 60 秒的部分作为流的内容。 直播（type=live）：格式为 0-[duration_in_seconds]。定义拉取与转推直播流的总时长，例如 0-60 表示持续转推 60 秒的直播分发。
pullStreamHeaders	Array	否	拉取源流时携带的自定义 HTTP Header 对象数组。 注意： 1. 总长度不能超过 2KB。 值不能包含单引号 (')、双引号 (")、连续两个分号 (;;)、逗号 (,) 或换行符。 示例：[{"headerKey": "User-Agent", "headerValue": "MyCustomPlayer/1.0"}, {"headerKey": "Referer", "headerValue": "http://example.com"}]

forward 对象参数

字段	类型	是否必填	描述
url	String	是	录制文件转推的目标RTMP地址。可填写多个URL，系统会将每个目标视为独立的转推任务。
resetUrl	String	否	恢复任务（cmd=5）时使用的新目标地址。

**注意：**目前仅支持RTMP协议作为转推目标地址。

fops 对象参数（转码）

字段	类型	是否必填	描述
bps	String	否	目标视频码率（单位：比特每秒），如1200000表示1.2 Mbps。
res	String	否	目标分辨率（如：1280x720）。x必须为小写。
fps	字符串	否	目标帧率（如 25）。
vcodec	字符串	否	输出视频编解码器（如 libx264、libx265）。如未设置，输出将保留源视频的编解码器。若使用水印，vcodec 必须设置为 libx264。
acodec	字符串	否	输出音频编解码器（如 libmp3lame、libfaac、libvorbis）。如未设置，输出将保留源音频的编解码器。
bufferTime	字符串	否	针对 HLS 源的缓冲时长（单位：秒），用于吸收源端不稳定，默认值为 0。设置后会增加延迟。
forced_gopInterval	字符串	否	期望的关键帧间隔，单位为毫秒（如 3000 表示 3 秒 GOP）。

extendParam 对象参数

字段	类型	是否必填	描述
waitCrtUrlFinish	String	否	当使用cmd=3更新点播文件的src列表时，设置为1表示等待当前文件播放完毕后再切换；0（默认）表示立即切换。
loop	String	否	控制点播文件的循环行为。默认值为1（播放一次）。使用-1为无限循环。 注意： 如果同时设置了loop和任务的end时间，则end时间优先。
index	String	否	仅适用于点播任务（type=video）。通过位置（索引）指定src列表中的起始文件。默认值为1，即从第一个文件开始。

参数优先级说明：
当为某个任务同时设置了end（在list对象中）、loop（在extendParam中）和relofftime（在src对象中）时，优先级顺序为：end > loop > relofftime。任务将根据已满足的优先级最高的参数停止。

API响应

API会返回标准HTTP状态码以及包含业务状态的JSON数据体。

示例成功响应：

{
    "http_code": "200",
    "msg": "任务接收成功！",
    "call_time": 1479952114000
}

常见HTTP状态码：

• 200 OK: 请求已接受，请在JSON体内查看业务级处理结果。
• 400 Bad Request: 请求格式错误（例如，JSON无效，缺少必填字段）。
• 403 Forbidden: 认证失败（例如，k签名错误，r值无效，超出请求速率限制）。
• 5xx Server Error: 服务器发生了意外错误。

JSON体内的业务级http_code：

HTTP	http_code	msg 示例	描述	建议操作
200	200	receive task success!	任务已成功接收并加入队列等待处理。	无需操作。
400	1001	cmd is error	cmd 字段不正确。	cmd 仅支持 1、2、3、5。
400	1001	type is error	type 字段不正确。	type 仅支持 live 或 video。
400	1001	list is null	缺少或未填写 list 数组。	此字段为必填项。
400	1001	params id is null	list 对象中的 id 字段缺失或未填写。	此字段为必填项。
400	1001	params src list is null	缺少或未填写 src 数组。	此字段为必填项。
400	1001	params src num is too long	src 数组中的项数超过限制。	最大支持 800 项，请减少源数量。
400	1001	params src length is too long	src 数组内容的总字符数超出限制。	最大字符数为204,800，请减少内容大小（例如：缩短URL）。
400	1001	params src is error	src 对象中的 url 缺失或为空。	该字段为必填项。
400	1001	params relofftime is error	relofftime 格式不正确。	请参阅参数说明，获取正确格式。
400	1001	params forward list is null	forward 数组缺失或为空。	该字段为必填项。
400	1001	params forward is error	forward 对象中的 url 缺失或为空。	该字段为必填项。
400	1001	params start format is error	start 时间格式不正确。	必须为13位的Unix时间戳（毫秒）。
400	1001	params end format is error	end 时间格式不正确。	必须为13位的Unix时间戳（毫秒）。
400	1001	params end plan is error!	end 时间早于当前时间。	结束时间必须大于当前时间。
400	1001	params start and end interval Too Brief!	start 与 end 之间的时间间隔过短。	最小间隔为5分钟。
400	1001	params ${field} format is error	指定字段的格式不正确。	请参考API文档获取指定字段的正确格式。
403	1002	apiName, n, r, k not exist or empty	缺少一个或多个认证参数。	请确保请求URL中包含 n、r 和 k。
403	1002	random.length gt 32 or key.length ne 32	参数 r 或 k 的长度不正确。	r 不能超过32个字符，k 必须为32个字符。
403	1002	you do not have right to access this api	您无权使用此高级API。	请确认您的账号已开通高级API访问权限。该权限生效可能需要5-10分钟。
403	1002	k is error	k 参数（MD5签名）不正确。	请核查您的MD5计算方法及私钥。
403	1002	frequency is great than limitCount	已超过API调用频率限制。	请降低调用频率。限制一般每5分钟刷新一次（例如，每5分钟100次）。
403	1002	random is repeat	r 参数值在短时间内重复。	请确保每次请求中的 r 都唯一，建议使用时间戳。
403	1002	user and host not relation	该账号无指定Domain的访问权限。	对于子账号，请确保该Domain已在控制台的Domain列表中配置。

任务查询

该接口用于获取任务的状态和详细信息。

• HTTP 方法: GET
• 接口地址: http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action

示例请求 URL：

http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action?n=test&r=1741165183&k=a6edsa3c30d64e172b52136ba493ad1f&id=task_unique_id_001

查询入参

字段	是否必需	描述
n, r, k	是	标准认证入参。
id	条件必需	唯一任务 id（精确匹配）。
src	条件必需	源URL（模糊匹配）。
forward	条件必需	转推目标URL（模糊匹配）。
pageNo	否	分页结果的页码。默认为 1。
pageSize	否	每页返回结果数。默认为 100，最大为 100。

注意：id、src 或 forward 至少需要提供一个。

查询响应体

示例查询响应：

{
    "total": 1,
    "pageNo": 1,
    "pageSize": 100,
    "list": [
        {
            "id": "task_unique_id_001"
            "type": "cloud live streaming",
            "src": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
            "forward": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
            "cmd": "1",
            "code": "0",
            "msg": "开始推流！",
            "startTime": "2025-03-05 16:05:12",
            "endTime": ""
        }
    ]
}

回调

如果在任务创建请求中提供了 transcallbackurl，系统将在任务状态变更时，向该URL发送带有JSON载荷的POST请求，以通知您任务的状态更新。

回调示例内容：

{
    "id": "task_unique_id_001",
    "srcurl": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
    "forwardurl": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
    "cmd": "1",
    "code": "0",
    "msg": "开始转推！",
    "event_time": 1600402486054
}

回调 code 与 msg 参考

code	msg 描述	含义
0	Start pushing!	推流已成功启动。
1	Push stream success	任务正常完成（例如点播文件播放结束，或达到预定结束时间）。
2	live_pull failed:xxxxx	由于外部错误（如源流不可用、连接丢失），转推已停止。
3	Push stream failed!	由于服务器内部错误，转推已停止。
4	(file): Server returned 404...	出现非关键警告（如播放列表中的点播文件未找到）。任务将尝试继续处理下一个条目。
5	list update success	信息性更新，通常用于点播轮播，表示有新文件正在处理。
90	任务不存在	未找到所请求的任务ID（适用于 cmd 值为 2、3、5 时）。
91	任务已存在，未启动！	已有相同目标URL的任务在运行。
92	任务启动分发失败！	系统未能成功启动该任务。请重试。

重要说明

1. 任务生命周期：
   • 实时性：如未指定 start 和 end，则任务将一直运行，直到调用 cmd=2 或源stream断开连接。
   • 定时任务：如果同时指定了 start 和 end，任务将在该时间窗口内运行。也可以通过 cmd=2 提前停止任务。
2. 时间约束：
   • 指定的 start 和 end 时间间隔必须至少为 5 分钟。
   • end 时间必须大于当前时间。
3. 转码：如需在 fops 中设置任何转码参数（如 bps、res 或 fps），则必须同时指定 vcodec。
4. 更新任务（cmd=3）：该命令用于更新已在运行中的任务的源（src）。您还可以在更新请求中包含 fops 和 extendParam。注意：如定时任务尚未开始，需先通过 cmd=2 取消原任务，随后使用更新后的配置新建任务。
5. 恢复任务（cmd=5）：该命令用于恢复已停止的任务，仅可在任务停止后 48 小时内使用。停止任务有两种情况，对应不同的恢复行为：
   • 自然停止：当 src 列表中的所有文件均播放完成时自动停止。使用 cmd=5 恢复时，将从列表中的第一个文件重新开始任务。
   • 手动停止：通过执行 cmd=2 指令手动停止任务。使用 cmd=5 恢复时，将从中断点继续执行任务。

恢复请求会忽略fops和extendParam参数，仅需确保id、src和forward参数与原任务匹配。如需指定新的目标地址，请使用resetUrl。

6. 停止任务（cmd=2）：

• 此命令用于停止指定任务的转推，id需与正在运行的任务一致。
• 如需停止向某个特定目标进行转推（当任务存在多个转推目标时），请在stop请求的forward数组中仅包含该目标的URL。
• 若需终止整个任务，建议在cmd=2请求中的forward列表包含该任务当前全部活动的转推URL，或与任务创建（或最近一次更新）时提供的完整forward列表保持一致。
• 停止请求中forward数组内的URL，必须与任务创建（cmd=1）或最后一次变更（cmd=3）时使用的URL完全一致。
• 仅当所有关联的转推流均已成功停止时，该任务才被视为完全终止。

7. 频率限制：请注意API调用的频率限制（通常为每5分钟100次），超过限制会返回403 Forbidden错误。
8. 参数格式化：请注意格式区别：在API请求中，src和forward为JSON数组，但在回调消息的srcurl和forwardurl字段中，将以字符串化的JSON方式传递。