回调内容说明--视频直播-火山引擎

文档中心

视频直播

回调管理

回调内容说明

当直播域名完成回调功能配置后，触发相关事件时，火山引擎将以 POST 请求的方式，主动向业务服务器发送携带事件信息的 JSON 数据包。

网络协议

请求方式：HTTP POST 请求。
请求头：默认 Content-Type 为 application/json。
请求体：为结构化 JSON 格式，具体字段请参见回调内容。
应答机制：业务服务器需返回状态码 200 OK，服务端仅以状态码判断是否成功接收，不关心应答体的具体内容。

请求可靠性

为确保回调请求的稳定送达，服务端具备如下重试机制：

初始请求失败后会立即进行最多 3 次、间隔 3 秒的短期重试。
若仍失败，进入队列继续重试，最长重试时间为 10 分钟，该时间从首次请求发起时开始计算，超时后不再重试。
以下情况会被判定为请求失败：
- 请求超时，即 4 秒内未收到应答；
- HTTP 状态码非 200。

公共安全签名参数

为确保回调请求来源的合法性，每个事件请求都包含签名字段，业务服务器需验证签名是否有效。

字段	类型	说明
sign	String	事件通知请求安全签名 `sign = MD5 ( AuthKeyPrimary + t )` 。说明火山引擎将回调密钥 `AuthKeyPrimary` 和过期时间 `t` 进行字符串拼接后通过 MD5 计算得出 `sign` 值，并将其放在通知消息里，业务服务器在收到事件通知请求后，根据同样的算法确认 `sign` 合法性，进而确认事件通知请求是否确实来自火山引擎。
t	Int64	过期时间，事件通知请求签名过期 Unix 时间戳。说明来自火山引擎的事件通知请求默认过期时间是 10 分钟，如果一条事件请求通知中的 `t` 值所指定的时间已经过期，则可以判定此条事件请求通知无效，通过此方法可以防止网络重放攻击。

回调内容

以下为不同回调事件类型的说明及字段详解，包括推流开始/结束、录制事件、截图、审核结果等。

推流开始事件

字段	类型	说明
vhost	String	域名空间。
domain	String	推流域名。
app	String	App 名称。
stream	String	流名称。
priority	Int	推流优先级参数。
backup_count	String	同名在线流数量。
event_type	String	事件名，固定值为 `push_start`，表示开始推流。
sign	String	公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
t	Int	公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
time	Int	开始推流时间，单位为秒。
time_ms	Int	开始推流时间，单位为毫秒。
transcoded	Boolean	是否为转码流。 `true`：转码流。 `false`：非转码流。
fp_node_ip	String	推流节点 IP。
fp_client_ip	String	推流客户端 IP。
fp_user_url	String	推流请求携带的 URL 参数。
session_id	String	本次推流的会话 ID。
sequence_id	String	本次推流的的推流序列 ID，是一次推流的唯一标识。

示例

{
    "code":0,
    "message":"ok",
    "data":{
        "vhost":"push.example.com",
        "domain":"push.example.com",
        "app":"live",
        "stream":"stream-123456",
        "event_type":"push_start",
            "sign":"",
            "t":0,
        "detail":{
            "time":1640849510,
            "time_ms":1640849510029,
            "transcoded":false,
            "priority":"2",
            "backup_count":"1",
            "fp_node_ip":"10.10.10.1",
            "fp_client_ip":"10.10.10.2",
            "fp_user_url":"",
            "session_id":"3693930911_150.139.1.1",
            "sequence_id":"027-20241313130E.1231423483"
        }
    }
}

推流结束回调消息

字段	类型	说明
vhost	String	域名空间。
domain	String	推流域名。
app	String	App 名称。
stream	String	流名称。
priority	Int	推流优先级参数。
backup_count	String	同名在线流数量。
event_type	String	事件名，固定值为 `push_end`，表示推流结束。
sign	String	公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
t	Int	公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
errmsg	String	详情请参考断流原因。
time	Int	结束推流时间，单位为秒。
time_ms	Int	结束推流时间，单位为毫秒。
transcoded	Boolean	是否为转码流。 `true`：转码流。 `false`：非转码流。
fp_node_ip	String	推流节点 IP。
fp_client_ip	String	推流客户端 IP。
fp_user_url	String	推流请求携带的 URL 参数。
session_id	String	本次推流的会话 ID。
sequence_id	String	本次推流的的推流序列 ID，是一次推流的唯一标识。

示例

{
    "code":0,
    "message":"ok",
    "data":{
        "vhost":"push-rtmp.example.com",
        "domain":"push-rtmp.example.com",
        "app":"live",
        "stream":"stream-123456",
        "event_type":"push_end",
            "sign":"",
            "t":0,
        "detail":{
            "time":1640849502,
            "time_ms":1640849502762,
            "transcoded":false,
            "priority":"2",
            "backup_count":"1",
              "errmsg":"func:OnStop:eof",
            "fp_node_ip":"10.10.10.1",
            "fp_client_ip":"10.10.10.2",
            "fp_user_url":"",
            "session_id":"3693930911_150.139.1.1",
            "sequence_id":"027-20241313130E.1231423483"
        }
    }
}

录制回调消息

字段	类型	说明
account_id	String	账号 ID。
vhost	String	域名空间。
domain	String	推流域名。
app	String	App 名称。
stream	String	流名称。
priority	Int	推流优先级。主备流场景下用于标识当前流的优先级，若无优先级则不返回该字段。
event_type	String	事件名称，固定为 `record_event`，表示录制事件。
sign	String	公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
t	Int	公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
detail	Object of detail	详细信息。

detail

字段	类型	说明
tos_bucket	String	保存在对象存储中的 bucket 名称。
tos_object	String	录制文件在对象存储中的完整路径。
uri	String	若录制内容保存在点播中，此字段为该录制视频在点播中的 `vid`。
duration	Int	录制长度，单位毫秒。
duration_ms	Int	已废弃。
start_time	Int	录制开始时间，Unix 时间戳，单位为秒。
start_time_ms	Int	已废弃。
stop_time	Int	录制结束时间，Unix 时间戳，单位为秒。
format	String	录制格式。支持的取值如下所示。 `mp4` `m3u8` `flv`
url	String	文件地址。说明如果录制文件保存在视频点播中，`url` 的返回结果为空，需使用 `uri` 或者 `vod_filename` 从点播中获取播放地址。
data_source	String	已废弃。
account_id	String	账号 ID。
task_id	String	任务 ID。
size	Long	录制文件的大小，单位为字节。
width	Int	录制文件的宽度，单位为像素。
height	Int	录制文件的高度，单位为像素。
extra	String	已废弃。
s3_endpoint	String	已废弃。
codec	String	已废弃。
vod_filename	String	录制文件在视频点播中的路径。

示例

录制存储在 VoD

{
    "code":0,
    "message":"ok",
    "data":{
        "account_id":"10000**",
        "vhost":"push.example.com",
        "domain":"push.example.com",
        "app":"live",
        "stream":"stream_123456",
        "priority":"1",
        "event_type":"record_event",
         "sign":"",
         "t":0,
        "detail":{
            "tos_bucket":"",
            "tos_object":"record/push.example.com/live/stream_123456_1640847072_1640849947_record.m3u8",
            "uri":"v0df17g10000ca6ut9pka0prk****pig",
            "duration":2868674,
            "duration_ms":2868674,
            "start_time":1640847072,
            "start_time_ms":0,
            "stop_time":1640849947,
            "format":"m3u8",
            "url":"",
            "data_source":"",
            "account_id":"10000**",
            "task_id":"1234",  
            "size":28361,
            "width":1280,
            "height":720,
            "extra":"{}"
            "s3_endpoint":"",
            "codec":"",                     
            "vod_filename":"record/{PubDomain}/{App}/{Stream}/{StartTime}_{EndTime}"
        }
    }
}

录制存储在 ToS

{
    "code": 0,
    "message": "ok",
    "data": {
        "account_id":"10000**",    
        "vhost": "push.example.com",
        "domain": "push.example.com",
        "app": "live",
        "stream": "stream_12345",
        "event_type": "record_event",
        "sign":"",
        "t":0,
        "detail": {
            "tos_bucket": "livetest",
            "tos_object": "record/record/push.example.com/live/stream_123456/1653469134_1653469220.m3u8",
            "uri": "",
            "duration": 84430,
            "duration_ms":84430,            
            "start_time": 1653469134,
            "start_time_ms":0,            
            "stop_time": 1653469220,
            "format": "m3u8",
            "url": "http://livetest.tos.volces.com/record/record/push.example.com/live/stream_12345/1653469134_1653469220.m3u8",
            "data_source":"",
            "account_id":"10000**",
            "task_id":"1234",             
            "size": 689,
            "width":1280,
            "height":720,
            "extra":"{}"
            "s3_endpoint":"",
            "codec":""                     
        }
    }
}

截图回调消息

字段	类型	说明
Vhost	String	域名空间。
Domain	String	推流域名。
App	String	App 名称。
Stream	String	流名称。
StreamURL	String	已废弃。
Bucket	String	保存在对象存储中的 bucket 名称。
ObjectKey	String	存储的文件路径。
Height	Int	图片高度，单位为像素。
Width	Int	图片宽度，单位为像素。
Format	String	录制格式。
TimeStamp	Int	截图时间，Unix 时间。
AccountId	String	账号 ID。
ImageXURI	String	截图存储在 veImageX 时，veImageX 为图片分配的资源 URI。
ServiceID	String	截图存储在 veImageX 时，veImageX 的服务 ID。
event_type	String	事件名，固定值为 `snapshot_event`，表示截图事件
sign	String	公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
t	Int	公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。

示例

截图存储在 veImageX

{
    "Vhost": "push.example.com",
    "Domain": "push.example.com",
    "App": "live",
    "Stream": "stream_1234",
    "StreamURL":"",
    "Bucket": "bucket1",
    "ObjectKey": "push.example.com/live/stream_1234/2022052510115****.jpg",
    "Height": 1080,
    "Width": 1920,
    "Format": "jpg",
    "TimeStamp": 1653473517,
    "AccountId": "2000001174",
    "event_type":"snapshot_event",
    "ImageXURI": "tos-cn-i-exampleid/2022052510115****.jpg",
     "sign":"",
     "t":0,
    "ServiceID": "exampleid"
}

截图存储在 ToS

{
    "Vhost":"push.example.com.",
    "Domain":"push.example.com",
    "App":"live",
    "Stream":"stream_1234",
    "StreamURL":"",
    "Bucket":"bucket1",
    "ObjectKey":"pushp.example.com/live/20211****.jpeg",
    "Height":864,
    "Width":480,
    "Format":"jpeg",
    "TimeStamp":1640849845,
    "sign":"",
     "t":0,
    "AccountId":"10000",
    "event_type":"snapshot_event",
}

拉流转推回调消息

字段	类型	说明
action	String	事件。 `init`：任务开始； `done`：任务结束； `live_start`：直播开始； `vod_start`：点播开始； `alarm`：任务告警； `stop`：断流。
description	String	事件的补充说明，简要描述导致当前状态或告警的原因。
event_time	Int	事件的时间，Unix 时间戳，单位为纳秒。
task_id	String	创建的任务 ID。
dst	String	推流地址。
type	Int	视频来源类型。 `0`：表示直播； `1`：表示点播。
cycle_mode	Int	点播文件的循环方式。当源流类型为点播时（`Type=1`），`CycleMode` 取值为 `-1`，表示按照列表顺序循环。
event_type	String	事件名，固定值为 `live_pull_to_push`，表示拉流转推事件。
src	String	视频来源的地址。当视频来源为直播时，表示直播的拉流地址；当视频来源为点播时，表示当前点播素材的播放地址。
play_progress	Float	当前点播素材的播放时长，单位为秒，保留 2 位小数。该字段仅在视频来源为点播时（`Type=1`）返回。
msg	CallbackMsg	任务回调的详细信息，包含错误类型及具体描述等。

CallbackMsg

参数名	类型	描述
type	String	回调消息类型，支持以下取值。 `PullFileUnstable`：当回调 `action` 为 `alarm` 时，表示拉流转推任务的源流拉取不稳定。 `PushStreamUnstable`：当回调 `action` 为 `alarm` 时，表示拉流转推任务的推流不稳定。 `PullFileFailed`：当回调 `action` 为 `stop` 时，表示拉流转推任务因源流拉取失败而断流退出。 `PushStreamFailed`：当回调 `action` 为 `stop` 时，表示拉流转推任务因推流失败而断流退出。 `FileEndEarly`：当回调 `action` 为 `stop` 时，表示拉流转推任务在到达任务结束时间之前提前结束，可能原因是点播文件播放次数达到限制等。
error	String	当回调为异常信息时，对应的错误类型。
message	String	当回调为异常信息时，对应的错误的具体描述。

参数名

类型

描述

type

String

回调消息类型，支持以下取值。

PullFileUnstable：当回调 action 为 alarm 时，表示拉流转推任务的源流拉取不稳定。
PushStreamUnstable：当回调 action 为 alarm 时，表示拉流转推任务的推流不稳定。
PullFileFailed：当回调 action 为 stop 时，表示拉流转推任务因源流拉取失败而断流退出。
PushStreamFailed：当回调 action 为 stop 时，表示拉流转推任务因推流失败而断流退出。
FileEndEarly：当回调 action 为 stop 时，表示拉流转推任务在到达任务结束时间之前提前结束，可能原因是点播文件播放次数达到限制等。

error

String

当回调为异常信息时，对应的错误类型。

message

String

当回调为异常信息时，对应的错误的具体描述。

示例

{
    "action":"stop",
    "description": "src_addr_invalid",
    "event_time":1650263223542095385,
    "task_id":"5f4c37605b7d711b51e28d73fa60****",
    "dst":"rtmp://push.example.com/live/teststream",
    "type":1,
    "cycle_mode":-1,
    "event_type": "live_pull_to_push",
    "src":"http://pull.example.com/live/test.m3u8",
    "play_progress":0,
    "msg": {
       "type": "PullFileFailed",
      "error": "HTTP_NOT_FOUND",
      "message": "Server returned 404 Not Found"
    }
}

截图审核结果回调消息

字段	类型	说明
vhost	String	域名空间。
Domain	String	推流域名。
App	String	应用名称。
Stream	String	流名称。
EventType	String	事件类型，默认为 `scan_screenshoot_event`，表示截图审核事件
sign	String	公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
t	Int	公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
EventData	EventData	事件详情。
EventTime	String	事件产生时间，RFC3339 格式的 UTC 时间。单位为秒。
EventId	String	事件 ID，用于事件去重。

EventData

参数名	类型	描述
MediaType	Int	可能违规的内容类型。截图审核的默认取值为 `1`，表示直播截图。
Image	String	审核截图保存的 uri，根据您配置的审核规则，返回截图在 TOS、veImageX 中的存储路径
HitLabels	Array of String	截图的违规原因。支持以下取值。 `301`：涉黄； `302`：涉敏1； `303`：涉敏2； `304`：广告； `305`：引人不适； `306`：违禁； `307`：二维码； `308`：诈骗； `309`：不良画面； `310`：未成年相关； `320`：文字违规。
RiskHit	Array of Risk	命中的违规列表。
RiskALL	Array of Risk	已配置的所有模型列表。
Decision	String	根据违规命中情况，给出的操作建议。支持的取值与含义如下所示。 `PASS`：审核通过； `REVIEW`：需要人工复审； `BLOCK`：不通过，建议召回。
AIResultOrigin	String	审核平台返回的响应原数据。

Risk

参数名	类型	描述
Label	String	截图命中的违规类型标签。支持以下取值。 `301`：涉黄； `302`：涉敏1； `303`：涉敏2； `304`：广告； `305`：引人不适； `306`：违禁； `307`：二维码； `308`：诈骗； `309`：不良画面； `310`：未成年相关； `320`：文字违规。
Sublabel	String	截图命中的违规子类型标签。
Decision	String	根据违规命中情况，给出的操作建议。支持的取值与含义如下所示。 `PASS`：审核通过； `REVIEW`：需要人工复审； `BLOCK`：不通过，建议召回。

参数名

类型

描述

Label

String

截图命中的违规类型标签。支持以下取值。

301：涉黄；
302：涉敏1；
303：涉敏2；
304：广告；
305：引人不适；
306：违禁；
307：二维码；
308：诈骗；
309：不良画面；
310：未成年相关；
320：文字违规。

Sublabel

String

截图命中的违规子类型标签。

Decision

String

根据违规命中情况，给出的操作建议。支持的取值与含义如下所示。

PASS：审核通过；
REVIEW：需要人工复审；
BLOCK：不通过，建议召回。

示例

{
    "Vhost": "push.example.com",
    "Domain": "push.example.com",
    "App": "live",
    "Stream": "stream1",
    "EventType": "scan_screenshoot_event",
    "sign":"",
      "t":0,
    "EventData": {
        "MediaType": 1,
        "Image": "/liveexample/tob****01/stream**/1659079720209.jpg",
        "HitLabels": [
            "301"
        ],
        "RiskHit": [
            {
                "Label": "301",
                "SubLabel": "301001",
                "Decision": "BLOCK"
            },
            {
                "Label": "301",
                "SubLabel": "301002",
                "Decision": "BLOCK"
            }
        ],
        "RiskALL": [
            {
                "Label": "301",
                "SubLabel": "301001",
                "Decision": "BLOCK"
            },
            {
                "Label": "301",
                "SubLabel": "301002",
                "Decision": "BLOCK"
            }
        ],
        "Decision": "BLOCK",
        "AIResultOrigin": "{\"RequestId\":\"202207291528410102091561590F291DAA\",\"Code\":0,\"Message\":\"success\",\"Data\":{\"DataId\":\"7125691570795811116\",\"Decision\":\"BLOCK\",\"Results\":[{\"Label\":\"301\",\"SubLabel\":\"301001\",\"Decision\":\"BLOCK\",\"score\":0,\"Detail\":null,\"Frames\":null},{\"Label\":\"301\",\"SubLabel\":\"301002\",\"Decision\":\"BLOCK\",\"score\":0,\"Detail\":null,\"Frames\":null}],\"Scores\":null}}"
    },
    "EventTime": "2022-07-29T15:28:40+08:00",
    "EventId": "71256915707958766**",
    "CallbackURL": [
        "http://example.com/callback/scan_screenshoot"
    ]
}

拉流录制任务状态回调消息

字段	类型	说明
vhost	String	域名空间。名称。
app	String	应用名称。
stream	String	流名称。
event_type	String	事件名，固定值为 `record_ts`，表示拉流录制任务状态回调。
record_status	String	事件名。 `record_started`：录制已经成功开始。 `record_stop`：录制中断、断流。
task_id	String	任务 ID。
tos_bucket	Object	保存在对象存储中时的详细信息，见下表。
vod_namespace	Object	保存到视频点播中时的详细信息，见下表。
service_id	String	截图存储在 veImageX 时，veImageX 的服务 ID。
time	Int	回调时间，单位为秒。
time_ms	Int	回调时间，单位为毫秒。
msg	String	录制状态回调消息，当 `RecordStatus` 为 `record_stop` 时，回调消息：直播断流。回源断流。

tos_bucket

字段	类型	说明
flv	String	FLV 录制的 bucket ，设置为空时不展示。
hls	String	HLS 录制的 bucket ，设置为空时不展示。
mp4	String	MP4 录制的 bucket ，设置为空时不展示。

vod_namespace

字段	类型	说明
flv	String	FLV 录制的 namespace ，设置为空时不展示。
hls	String	HLS 录制的 namespace ，设置为空时不展示。
mp4	String	MP4 录制的 namespace ，设置为空时不展示。

示例

保存在对象存储中

{
    "code":0,
    "message":"ok",
    "data":{
        "vhost":"push.example.com",
        "app":"live",
        "stream":"livestream001",
        "event_type":"record_ts",
        "detail":{
            "record_status":"record_started",
            "task_id":"f831f3b0********1aa4dcf7621",
            "tos_bucket":{
                "hls":"live-****-test1"
            },
            "vod_namespace":{
                // 点播空间内容为空
            },
            "time":1688717767,
            "time_ms":1688717767506,
            "msg":""
        }
    }
}

保存在视频点播中

{
    "code":0,
    "message":"ok",
    "data":{
        "vhost":"live.example.push.com",
        "app":"live",
        "stream":"livestream001",
        "event_type":"record_ts",
        "detail":{
            "record_status":"record_stop",
            "task_id":"f831f3b0********1aa4dcf7621",
            "tos_bucket":{
                // 对象存储信息为空
            },
            "vod_namespace":{
                "hls":"live**tt"
            },
            "time":1688717870,
            "time_ms":1688717870948,
            "msg":"CreateRelaySourceError"
        }
    }
}

断流原因

常见的断流原因如下所示，如您获取的断流原因不在下表或您无法判断处理方法，请创建工单联系技术支持进行处理。

errmsg	说明
func:HandleInputPacket:net:func:Input:rtmp:FLV Signature don't match	FLV 协议解析失败导致推流断开。
func:HandleInputPacket:net:func:Input:rtmp:close stream id 0 don't match 1	RTMP 协议不兼容导致推流断开。
func:conn.Read:net:local error: tls: bad record MAC	TLS 协议失败导致推流断开。
func:timeout:idle_too_long	推流端长时间没有数据传输导致超时断开。
io:conn_reset_by_peer	推流端非通过正常停止直播操作导致的推流断开，如网络中断、直接关闭推流软件等。
func:conn.Read:net:read_i/o_timeout	视频直播中心数据 I/O 错误导致的推流断开。
param:Priority:priority	被高优先级流推流导致的低优先级流推流断开。
auth:JudgePublishAuth:timeout:invalid_sign	URL 鉴权参数字段无效、鉴权超时等原因导致推流断开。
func:OnStatus:func:RtmpStatusCode2NssError:not_allowed	直播流被禁用导致的推流断开。
func:OnStatus:func:RtmpStatusCode2NssError:api_close	调用 `KillStream` 接口流断开直播。
func:sendEvent:param:receiver:not_running	视频直播中心内部错误，请联系技术支持。
auth:remote_auth:not_allowed	远程鉴权失败导致推流断开。
func:conn.Read:eof	复杂原因导致的推流断开，请联系技术支持。
func:OnStop:eof	推流端通过停止直播功能正常结束推流。
func:conn.Read:net:The socket was properly connected, but the connection has been broken	网络异常导致推流断开。
func:OnStatus:func:RtmpStatusCode2NssError:duplicate	使用相同流名称，进行推流导致推流断开。

最近更新时间：2026.06.01 17:47:14

这个页面对您有帮助吗？

有用

无用

视频直播

网络协议 #

请求可靠性 #

公共安全签名参数 #

回调内容 #

推流开始事件 #

推流结束回调消息 #

录制回调消息 #

detail

截图回调消息 #

拉流转推回调消息 #

CallbackMsg

截图审核结果回调消息 #

EventData

Risk

拉流录制任务状态回调消息 #

tos_bucket

vod_namespace

断流原因 #

网络协议

请求可靠性

公共安全签名参数

回调内容

推流开始事件

推流结束回调消息

录制回调消息

截图回调消息

拉流转推回调消息

截图审核结果回调消息

拉流录制任务状态回调消息

断流原因