You need to enable JavaScript to run this app.
导航
视频直播
  • 文档首页
    • /视频直播/API 参考/回调管理/回调内容说明
回调内容说明
最近更新时间：2025.07.08 11:34:04首次发布时间：2023.09.25 14:37:16
我的收藏
有用
有用
无用
无用

当直播域名完成回调功能配置后，触发相关事件时，火山引擎将以 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 值所指定的时间已经过期，则可以判定此条事件请求通知无效，通过此方法可以防止网络重放攻击。

回调内容

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

推流开始事件

字段类型说明
vhostString域名空间。
domainString推流地址。
appStringApp 名称。
streamString流名称。
priorityInt推流优先级参数。
backup_countString同名在线流数量。
event_typeString事件名，固定值为 push_start，表示开始推流。
signString公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
tInt公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
timeInt开始推流时间，单位为秒。
time_msInt开始推流时间，单位为毫秒。

transcoded

Boolean

是否为转码流。

  • true：转码流。
  • false：非转码流。
fp_node_ipString推流节点 IP。
fp_client_ipString推流客户端 IP。
fp_user_urlString推流请求携带的 URL 参数。
session_idString本次推流的会话 ID。
sequence_idString本次推流的的推流序列 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"
        }
    }
}

推流结束回调消息

字段类型说明
vhostString域名空间。
domainString推流地址。
appStringApp 名称。
streamString流名称。
priorityInt推流优先级参数。
backup_countString同名在线流数量。
event_typeString事件名，固定值为 push_end，表示推流结束。
signString公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
tInt公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
errmsgString详情请参考断流原因。
timeInt结束推流时间，单位为秒。
time_msInt结束推流时间，单位为毫秒。

transcoded

Boolean

是否为转码流。

  • true：转码流。
  • false：非转码流。
fp_node_ipString推流节点 IP。
fp_client_ipString推流客户端 IP。
fp_user_urlString推流请求携带的 URL 参数。
session_idString本次推流的会话 ID。
sequence_idString本次推流的的推流序列 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"
        }
    }
}

录制回调消息

字段类型说明
vhostString域名空间。
domainString推流地址。
appStringApp 名称。
streamString流名称。
priorityInt推流优先级。主备流场景下用于标识当前流的优先级，若无优先级则不返回该字段。
event_typeString事件名称，固定为 record_event，表示录制事件。
signString公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
tInt公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
tos_bucketString保存在对象存储中的 bucket 名称。
tos_objectString录制文件在对象存储中的完整路径。
uriString若录制内容保存在点播中，此字段为该录制视频在点播中的 vid。
durationInt录制长度，单位毫秒。
start_timeInt录制开始时间，Unix 时间戳，单位为秒。
stop_timeInt录制结束时间，Unix 时间戳，单位为秒。

format

String

录制格式。支持的取值如下所示。

  • mp4
  • m3u8
  • flv

url

String

文件地址。

说明

如果录制文件保存在视频点播中，url 的返回结果为空，需使用 uri 或者 vod_filename 从点播中获取播放地址。

vod_filenameString录制文件在视频点播中的路径。
account_idString账号 ID。
sizeLong录制文件的大小，单位为字节。

示例

  • 录制存储在 VoD
{
    "code":0,
    "message":"ok",
    "data":{
        "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,
            "start_time":1640847072,
            "stop_time":1640849947,
            "format":"m3u8",
            "url":"",
            "vod_filename":"record/{PubDomain}/{App}/{Stream}/{StartTime}_{EndTime}",
            "account_id":"10000**",
            "size":28361
        }
    }
}
  • 录制存储在 ToS
{
    "code": 0,
    "message": "ok",
    "data": {
        "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,
            "start_time": 1653469134,
            "stop_time": 1653469220,
            "format": "m3u8",
            "url": "http://livetest.tos.volces.com/record/record/push.example.com/live/stream_12345/1653469134_1653469220.m3u8",
            "account_id": "2000001174",
            "size": 689
        }
    }
}

截图回调消息

字段类型说明
VhostString域名空间。
DomainString推流地址。
AppStringApp 名称。
StreamString流名称。
BucketString保存在对象存储中的 bucket 名称。
ObjectKeyString存储的文件路径。
HeightInt图片高度，单位像素。
WidthInt图片宽度，单位像素。
FormatString录制格式。
TimeStampInt截图时间，Unix 时间。
AccountIdString账号 ID。
ImageXURIString截图存储在 veImageX 时，veImageX 为图片分配的资源 URI。
ServiceIDString截图存储在 veImageX 时，veImageX 的服务 ID。
event_typeString事件名，固定值为 snapshot_event，表示截图事件
signString公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
tInt公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。

示例

  • 截图存储在 veImageX
{
    "Vhost": "push.example.com",
    "Domain": "push.example.com",
    "App": "live",
    "Stream": "stream_1234",
    "Bucket": "bucket1",
    "ObjectKey": "push.example.com/live/stream_1234/2022052510115****.jpg",
    "Height": 1080,
    "Width": 1920,
    "Format": "jpg",
    "TimeStamp": 1653473517,
    "AccountId": "2000001174",
    "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",
    "Bucket":"bucket1",
    "ObjectKey":"pushp.example.com/live/20211****.jpeg",
    "Height":864,
    "Width":480,
    "Format":"jpeg",
    "TimeStamp":1640849845,
    "sign":"",
		"t":0,
    "AccountId":"10000"
}

拉流转推回调消息

字段类型说明

action

String

事件。

  • init：任务开始；
  • done：任务结束；
  • live_start：直播开始；
  • vod_start：点播开始；
  • alarm：任务告警；
  • stop：断流。
descriptionString事件的补充说明，简要描述导致当前状态或告警的原因。
event_timeInt事件的时间，Unix 时间戳，单位为纳秒。
task_idString创建的任务 ID。
dstString推流地址。

type

Int

视频来源类型。

  • 0：表示直播；
  • 1：表示点播。

cycle_mode

Int

点播文件的循环方式。
当源流类型为点播时（Type=1），CycleMode 取值为 -1，表示按照列表顺序循环。

event_typeString事件名，固定值为 live_pull_to_push，表示拉流转推事件。

src

String

视频来源的地址。

  • 当视频来源为直播时，表示直播的拉流地址；
  • 当视频来源为点播时，表示当前点播素材的播放地址。
play_progressFloat当前点播素材的播放时长，单位为秒，保留 2 位小数。该字段仅在视频来源为点播时（Type=1）返回。
msgCallbackMsg任务回调的详细信息，包含错误类型及具体描述等。

CallbackMsg

参数名类型描述

type

String

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

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

示例

{
    "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"
    }
}

截图审核结果回调消息

字段类型说明
vhostString域名空间。
DomainString推流域名。
AppString应用名称。
StreamString流名称。
EventTypeString事件类型，默认为 scan_screenshoot_event，表示截图审核事件
signString公共安全签名参数，用于验证请求来源的合法性。详见公共安全签名参数。
tInt公共安全签名参数，表示请求的过期时间。详见公共安全签名参数。
EventDataEventData事件详情。
EventTimeString事件产生时间，RFC3339 格式的 UTC 时间。单位为秒。
EventIdString事件 ID，用于事件去重。

EventData

参数名类型描述
MediaTypeInt可能违规的内容类型。截图审核的默认取值为 1，表示直播截图。
ImageString审核截图保存的 uri，根据您配置的审核规则，返回截图在 TOS、veImageX 中的存储路径

HitLabels

Array of String

截图的违规原因。支持以下取值。

  • 301：涉黄；
  • 302：涉敏1；
  • 303：涉敏2；
  • 304：广告；
  • 305：引人不适；
  • 306：违禁；
  • 307：二维码；
  • 308：诈骗；
  • 309：不良画面；
  • 310：未成年相关；
  • 320：文字违规。
RiskHitArray of Risk命中的违规列表。
RiskALLArray of Risk已配置的所有模型列表。

Decision

String

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

  • PASS：审核通过；
  • REVIEW：需要人工复审；
  • BLOCK：不通过，建议召回。
AIResultOriginString审核平台返回的响应原数据。

Risk

参数名类型描述

Label

String

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

  • 301：涉黄；
  • 302：涉敏1；
  • 303：涉敏2；
  • 304：广告；
  • 305：引人不适；
  • 306：违禁；
  • 307：二维码；
  • 308：诈骗；
  • 309：不良画面；
  • 310：未成年相关；
  • 320：文字违规。
SublabelString截图命中的违规子类型标签。

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"
    ]
}

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

字段类型说明
vhostString域名空间。名称。
appString应用名称。
streamString流名称。
event_typeString事件名，固定值为 record_ts，表示拉流录制任务状态回调。

record_status

String

事件名。

  • record_started：录制已经成功开始。
  • record_stop：录制中断、断流。
task_idString任务 ID。
tos_bucketObject保存在对象存储中时的详细信息，见下表。
vod_namespaceObject保存到视频点播中时的详细信息，见下表。
service_idString截图存储在 veImageX 时，veImageX 的服务 ID。
timeInt回调时间，单位为秒。
time_msInt回调时间，单位为毫秒。

msg

String

录制状态回调消息，当 RecordStatus 为 record_stop 时，回调消息：

  • 直播断流。
  • 回源断流。

tos_bucket

字段类型说明
flvStringFLV 录制的 bucket ，设置为空时不展示。
hlsStringHLS 录制的 bucket ，设置为空时不展示。
mp4StringMP4 录制的 bucket ，设置为空时不展示。

vod_namespace

字段类型说明
flvStringFLV 录制的 namespace ，设置为空时不展示。
hlsStringHLS 录制的 namespace ，设置为空时不展示。
mp4StringMP4 录制的 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 matchFLV 协议解析失败导致推流断开。
func:HandleInputPacket:net:func:Input:rtmp:close stream id 0 don't match 1RTMP 协议不兼容导致推流断开。
func:conn.Read:net:local error: tls: bad record MACTLS 协议失败导致推流断开。
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_signURL 鉴权参数字段无效、鉴权超时等原因导致推流断开。
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使用相同流名称，进行推流导致推流断开。