预警回调

更新时间：2026-07-02

预警回调

概述

通过预警回调功能，您可以将一见平台产生的预警消息实时推送到您指定的 URL 地址，实现预警信息的自动化处理和集成。一见平台支持通过 HTTP/HTTPS 协议的 POST 和 PUT 请求推送到可访问公网的 URL，您可基于回调接口推送的预警信息做进一步的处理，例如：对接内部告警系统、自动创建工单、发送通知等。

预警回调使用说明

回调地址配置：您需要提供能接收 HTTP/HTTPS 协议的 POST/PUT 请求，并且公网可访问的 URL 地址，作为回调地址。
回调触发场景：当预警产生、更新时会触发回调。支持包括技能产生预警、复判服务、人工复判、自动消警等多种触发场景，具体见下方「回调触发场景」章节。
两种回调接口：
- POST 请求：新增预警时触发，回调地址收到新预警的完整信息。
- PUT 请求：预警状态更新时触发（如消警、误报、处理状态变更等）。
返回要求：当向绑定的 URL 发出回调请求后，我们需要接收到标识成功的返回内容（HTTP 状态码 = 200），以表明已成功接收信息；否则将按策略重复发送回调请求。
鉴权方式（可选）：支持通过 API Key 进行鉴权，平台在回调请求的 HTTP Header 中透传 Authorization，由客户侧校验。

操作步骤

1. 配置回调地址

在一见平台导航中进入 预警通知 > 推送设置，配置回调 URL 地址。

回调地址：输入可接收 POST/PUT 请求的公网 URL（如 https://your-domain.com/callback/alarm）
API Key（可选）：如需鉴权，在此配置 API Key。平台将在回调请求的 Header 中透传此 Key，客户侧校验 Key 是否匹配，以确认请求来自一见平台。

2. 接收并处理回调

部署回调接收服务，处理一见平台推送的预警消息：

POST 请求：接收新产生的预警数据，可根据预警内容自动创建工单、发送通知或触发其他业务流程。
PUT 请求：接收预警状态更新，可根据更新的状态（如消警、误报、已处理等）更新内部系统中的对应记录。

3. 返回成功响应

回调接收服务处理成功后，需返回 HTTP 200 状态码告知平台已成功接收；否则平台将按策略重试。

鉴权方式

在预警推送设置中配置 API Key 后，回调请求的 HTTP Header 会携带 Authorization 字段：

Plain Text

1Authorization: your-api-key

客户侧接收回调时，校验 Authorization 头部的值是否与配置的 API Key 一致，一致则确认为来自一见平台的合法请求，不一致可拒绝处理。

此鉴权方式为可选配置，如不配置 API Key，则直接接收回调请求即可。

回调接口说明

1. 创建预警回调 POST

当预警首次产生时，平台向您的回调地址发送 POST 请求。

Plain Text

1POST $url

请求参数

参数	类型	说明	示例值
id	string	预警ID，全局唯一，后续更新也会用此ID标识	`11c821998a104cc7bfa01a8c3ccdf675`
name	string	预警名称	`区域入侵`
createdAt	time	预警创建时间	`2025-09-15T07:29:43+08:00`
updatedAt	time	预警更新时间	`2025-09-15T07:29:43+08:00`
triggerType	string	回调触发场景	`SkillAlarm`
status	string	预警状态	`pending` / `mistaken`
labels	string	预警处理状态	`read`（已查阅）
isCanceled	bool	是否已消警	`false`
level	int	预警等级（1~4，数字越大等级越低）	`4`
imageURL	string	预警截图地址（鉴权有时效，有效期24小时）	`https://s3.bj.bcebos.com/...`
videoURL	string	预警视频片段（可能为空，后续 PUT 更新会补全）	`https://s3.bj.bcebos.com/...`
eventTime	int64	预警发生时间戳（毫秒）	`1757892581655`
videoStartTime	int64	视频切片开始时间戳（毫秒）	`1757892581655`
videoEndTime	int64	视频切片结束时间戳（毫秒）	`1757892581655`
point	object	点位信息（点位ID、名称、部门等）	见下方点位信息结构
department	object	部门信息（id、name）	`{"id":"xxx","name":"xxx"}`
skill	object	技能信息（技能ID、名称等）	见下方技能结构
annotations	[]Annotation	检出目标标注列表	见下方 Annotation 结构
reports	[]AlarmReport	预警处理事件记录	见下方 AlarmReport 结构
manualRejudgeStatus	string	人工复判状态	`pending` / `completed` / 空
multiRejudgeStatus	string	大模型智能复判状态	`pending` / `completed` / 空
trackID	string	追踪ID	`xxx`

请求示例

                JSON
                
            

                {
    "id": "11c821998a104cc7bfa01a8c3ccdf675",
    "name": "区域入侵",
    "createdAt": "2025-09-15T07:29:43+08:00",
    "updatedAt": "2025-09-15T07:29:43+08:00",
    "status": "created",
    "isCanceled": false,
    "labels": "",
    "triggerType": "SkillAlarm",
    "manualRejudgeStatus": "",
    "multiRejudgeStatus": "",
    "point": {
        "id": "d99dfd8e904f4296a44c0e1a204794fc",
        "name": "通道4客区",
        "DeptID": "40f6c4565a5f4f4db5c836123e8a568f",
        "DeptName": "肯德基南京NJ1443店",
        "kind": "Device",
        "resourceID": "e241981e413044c387ba8b894fa57609",
        "resourceName": "NJ1443盒子",
        "resourceType": "Edge/Box",
        "gbID": "",
        "extraData": "{\"departmentId\":\"370779\"}"
    },
    "department": {
        "id": "40f6c4565a5f4f4db5c836123e8a568f",
        "name": "肯德基南京NJ1443店"
    },
    "imageURL": "https://s3.bj.bcebos.com/yijiandiapd07b4d490f81461294acb18cc4128683/storage/alarm-images/edge/2025-09-15/a8oaptarhe8twcfes4zcwv30lpqzp66g.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ALTAKHKNPg9xOIrqSyIzUkEqdG%2F20250914%2Fbj%2Fs3%2Faws4_request&X-Amz-Date=20250914T232942Z",
    "videoURL": "",
    "level": 4,
    "annotations": [
        {
            "bbox": [1377.0001220703, 682.66668701172, 419.00012207031, 396.89923095703],
            "bboxID": 0,
            "confidence": 0.97314453125,
            "categoryID": "person",
            "categoryName": "人体",
            "trackID": 22987,
            "segmentation": [[]],
            "meter": {
                "roi": null,
                "alarmResult": null,
                "valueResult": null
            }
        }
    ],
    "skill": {
        "id": "workspaces/public/skills/c-sk-rt5h7NkI",
        "name": "区域入侵",
        "tags": null
    },
    "reports": [
        {
            "id": "a62f61f1d54149e394e58608ad500923",
            "name": "[产生预警]通道4客区,区域入侵;",
            "createdAt": "2025-09-15T07:29:43+08:00",
            "updatedAt": "2025-09-15T07:29:43+08:00",
            "status": "pending",
            "description": "[产生预警]通道4客区,区域入侵;"
        }
    ],
    "trackID": "",
    "eventTime": 1757892581655,
    "videoStartTime": 0,
    "videoEndTime": 0
}
            

2. 更新预警回调 PUT

当预警状态发生变化时（如消警、误报、处理完毕等），平台向您的回调地址发送 PUT 请求。

Plain Text

1PUT $url

请求参数

参数	类型	说明	示例值
ids	[]string	预警ID列表	`["xxxxxxxxxxx"]`
status	string	预警处理状态	`mistaken`
isCanceled	bool	是否已消警	`true`
labels	string	预警处理情况	`read`（已阅）
alarmStatus	string	预警状态	`alarm` / `cancellation` / `escalation`
imageURL	string	截图链接	`https://s3.bj.bcebos.com/...`
videoURL	string	预警视频片段（鉴权有时效，有效期24小时）	`https://s3.bj.bcebos.com/...`
opinion	string	预警处理意见	`xxxxx`
updatedAt	time	预警更新时间	`2022-09-16T20:41:30+08:00`
extInfo	string	扩展信息
level	int	预警等级	`4`
triggerType	string	回调触发场景	`SkillAlarm`
manualRejudgeStatus	string	人工复判状态	`pending` / `completed` / 空
multiRejudgeStatus	string	大模型智能复判状态	`pending` / `completed` / 空
videoStartTime	int64	视频切片开始时间戳	`1757892581655`
videoEndTime	int64	视频切片结束时间戳	`1757892581655`

请求示例

                JSON
                
            

                {
    "ids": [
        "11c821998a104cc7bfa01a8c3ccdf675"
    ],
    "isCanceled": true,
    "updatedAt": "2022-06-01T13:59:58+08:00",
    "videoURL": "https://s3.bj.bcebos.com/yijiandiapd07b4d490f81461294acb18cc4128683/storage/alarm-images/edge/2025-09-15/a8oaptarhe8twcfes4zcwv30lpqzp66g.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ALTAKHKNPg9xOIrqSyIzUkEqdG%2F20250914%2Fbj%2Fs3%2Faws4_request&X-Amz-Date=20250914T232942Z",
    "status": "mistaken",
    "labels": "",
    "triggerType": "SkillAlarm",
    "manualRejudgeStatus": "",
    "multiRejudgeStatus": "",
    "opinion": "xxxxx",
    "extInfo": "",
    "level": 4,
    "videoStartTime": 1757892581655,
    "videoEndTime": 1757892581655
}
            

回调触发场景

触发场景	枚举值	说明
初始技能产生预警	`SkillAlarm`	技能检测到异常事件产生预警
复判服务	`ServiceRejudge`	平台复判服务完成复判
多模态大模型复判	`MultiRejudge`	多模态大模型对预警进行复判
人工复判	`ManualRejudge`	人工对预警进行复判
手动处理	`ManualReview`	人工手动处理预警
自动消警	`AutoCancel`	预警自动消除
手动产生预警	`ManualAlarm`	人工手动产生预警
预警升级	`LevelUpdate`	预警等级发生变化

数据结构说明

点位信息（point）

字段	类型	说明	示例值
id	string	点位ID	`c59802772c20034163e4498133589160`
name	string	点位名称	`机房监控摄像机-01`
streamURL	string	流地址	`rtsp://stream/test.com`
kind	string	点位类型	`Device`
gbID	string	国标ID	`12345`
resourceID	string	资源ID	`e241981e413044c387ba8b894fa57609`
resourceName	string	资源名称	`NJ1443盒子`
resourceType	string	资源类型	`Edge/Box`
extraData	string	扩展数据（如门店编码）	`{"departmentId":"370779"}`

技能信息（skill）

字段	类型	说明	示例值
id	string	技能ID	`workspaces/public/skills/c-sk-rt5h7NkI`
name	string	技能名称	`未带安全帽`
rois	[]object	电子围栏结构体	—
tags	map	技能标签	—

检出目标标注（Annotation）

字段	类型	说明	示例值
categoryID	string	检出目标ID	`c59802772c20034163e4498133589160`
categoryName	string	检出目标名称	`安全帽`
bbox	list	检出目标框 [x, y, w, h]，x/y为左上角坐标，w/h为宽高	`[100.61, 135.19, 58.48, 60.37]`
confidence	float	置信度	`0.97314453125`
trackID	int	跟踪ID	`22987`

预警处理事件（AlarmReport）

字段	类型	说明	示例值
id	string	预警处理ID	`a62f61f1d54149e394e58608ad500923`
name	string	预警处理名称	`[产生预警]通道4客区,区域入侵;`
createdAt	time	创建时间	`2025-09-15T07:29:43+08:00`
updatedAt	time	更新时间	`2025-09-15T07:29:43+08:00`
status	string	预警处理状态	`pending`
description	string	描述	`[产生预警]通道4客区,区域入侵;`

复判状态

复判状态	枚举值	说明
待复判	`pending`	等待复判中
复判完成	`completed`	复判已完成
空值	（空）	表示无需复判

预警处理进展状态（alarmReport.status）

状态	说明
`pending`	产生预警
`read`	人工查阅
`upgrade`	预警升级
`manual`	人工复判
`finished`	预警结束

重试机制

当回调请求发送失败或未返回 HTTP 200 时，平台将进行重试：

重试次数：最多重试 3 次
超时时间：每次请求超时为 5 秒
触发条件：未收到 HTTP 200 响应或请求超时

建议您的回调接收服务尽快返回 200 状态码，再异步处理预警数据，避免因处理耗时过长导致超时重试。

常见问题

1. imageURL 无法下载

可能原因：

鉴权已过期：图片/视频地址的鉴权默认有效期为 24 小时，请在预警产生后 24 小时内完成下载。
地址编码问题：下载地址中的 \u0026 需要转码为 & 后再下载。例如：

Plain Text

1原始地址：https://s3.bj.bcebos.com/...jpeg?X-Amz-Algorithm=...\u0026X-Amz-Credential=...
2正确地址：https://s3.bj.bcebos.com/...jpeg?X-Amz-Algorithm=...&X-Amz-Credential=...

2. 如何区分是新预警还是预警更新？

根据 HTTP 方法区分：

POST 请求 → 新产生的预警
PUT 请求 → 已有预警的状态更新

同时可通过 triggerType 字段判断具体触发场景。

3. videoURL 何时有值？

POST 请求中，videoURL 可能为空，视频正在生成中。
PUT 请求中，平台会补全 videoURL，建议在收到 PUT 回调时更新视频地址。

评价此篇文章

有帮助没帮助

技能相关接口

软硬一体

百度智能云

百度一见视觉智能体平台

百度一见视觉智能体平台

预警回调

预警回调

概述

预警回调使用说明

操作步骤

1. 配置回调地址

2. 接收并处理回调

3. 返回成功响应

鉴权方式

回调接口说明

1. 创建预警回调 POST

请求参数

请求示例

2. 更新预警回调 PUT

请求参数

请求示例

回调触发场景

数据结构说明

点位信息（point）

技能信息（skill）

检出目标标注（Annotation）

预警处理事件（AlarmReport）

复判状态

预警处理进展状态（alarmReport.status）

重试机制

常见问题

1. imageURL 无法下载

2. 如何区分是新预警还是预警更新？

3. videoURL 何时有值？

百度一见 视觉智能体平台

预警回调

预警回调

概述

预警回调使用说明

操作步骤

1. 配置回调地址

2. 接收并处理回调

3. 返回成功响应

鉴权方式

回调接口说明

1. 创建预警回调 POST

请求参数

请求示例

2. 更新预警回调 PUT

请求参数

请求示例

回调触发场景

数据结构说明

点位信息（point）

技能信息（skill）

检出目标标注（Annotation）

预警处理事件（AlarmReport）

复判状态

预警处理进展状态（alarmReport.status）

重试机制

常见问题

1. imageURL 无法下载

2. 如何区分是新预警还是预警更新？

3. videoURL 何时有值？

百度一见视觉智能体平台