算法分析接口文档

文档属性

文档属性	详情
文档版本	V1.6
编制日期	2026-04-28
适用范围	视频流检测接口（当前支持火焰、遗弃物、未戴安全帽）、VLM算法接口（当前支持提示词驱动的视频流分析、动态更新配置）

1. 概述

本文档定义了两类算法分析相关的标准化接口：

视频流检测接口：当前定义检测类型获取接口、启动接口、停止接口、HTTP 回调接口与 RTMP 实时推流五类视频流对接协议，已明确火焰、遗弃物、未戴安全帽三类异常检测结果的回调结构，并要求以 instanceId 关联巡逻任务实例。
VLM算法接口：定义提示词驱动的视频流分析协议，整体生命周期、回调结构与 RTMP 推流约定复用视频流检测接口，仅将启动接口扩展为显式传入自然语言提示词，并使用独立路径区分 VLM 任务。

当前已明确视频流检测接口与 VLM 算法接口规范；其中 VLM 接口与视频流检测接口共用相同的任务控制、回调和推流模式，仅在启动请求中新增 prompt 参数并切换到 VLM 专属路径。

2. 通用规范

HTTP 类接口请求与响应均采用 JSON 格式，Content-Type 固定为 application/json。
视频流实时推流链路使用 RTMP 协议，封装格式为 FLV，视频编码为 H.264。
接口基础路径遵循统一模块约定，算法相关 HTTP 接口统一使用 analysis 模块。
HTTP 写操作接口采用“资源复数 + 动作子路径”风格，统一使用 POST 方法。
需要做链路追踪与结果匹配的 HTTP 接口必须传入全局唯一 requestId，推荐使用 UUID 生成。
视频流检测接口由检测类型获取接口、启动接口、停止接口、HTTP 回调接口与 RTMP 实时推流组成；历史 FTP/FTPS 截图上传链路已废弃，不纳入本版规范。
视频流检测任务采用“启动 -> 检测 -> 告警回调 -> 停止”的生命周期模式；启动、停止与告警回调均须携带 instanceId，用于关联当前任务实例。
VLM 算法接口采用与视频流检测相同的“启动 -> 分析 -> 回调 -> 停止”生命周期模式；启动、停止与回调均须携带 instanceId，并在启动时额外传入 prompt 描述本次分析目标。
请求方必须提供可访问的回调 / 告警接收地址，算法服务按约定路径推送分析结果；地址不可用时视为调用方配置错误。
平台侧 HTTP 接口响应统一使用 Result<T> 结构：code、message、data；视频流检测回调接口成功处理时返回 HTTP 200 + Result<null>。
VLM 回调接口成功处理时同样返回 HTTP 200 + Result<null>，失败响应语义与视频流检测回调保持一致。
接口层业务状态码复用既有定义：成功返回 200，失败返回 500。
算法分析结果码通过业务数据中的 resCode 字段返回，严格复用现有 AnalysisResultCodeEnum 枚举，禁止自定义编码，保证系统解析逻辑无改造。
所有扩展字段（extParams / extInfo）均为非必填，用于透传个性化参数，不影响核心解析逻辑。

3. 视频流检测接口定义

3.1 接口概览

配置项	详情
接口名称	视频流检测接口
接口组成	检测类型获取接口 + 启动接口 + 停止接口 + HTTP 回调接口 + RTMP 实时推流
检测类型获取接口路径	`/api/v1/analysis/video-stream-detect-types`
启动接口路径	`/api/v1/analysis/video-stream-tasks/start`
停止接口路径	`/api/v1/analysis/video-stream-tasks/stop`
HTTP 回调路径	`/api/v1/analysis/video-stream-callbacks/create`
HTTP 请求方法	检测类型获取接口使用 `GET`；其余 HTTP 接口使用 `POST`
RTMP 推流地址	启动成功后由算法侧返回，格式为 `rtmp://{host}:{port}/drtm/{instanceId}`
接口描述	平台可先调用检测类型获取接口查询当前开放的视频流检测算法目录，再调用启动接口下发待检测视频流与任务实例 ID；算法侧受理成功后返回当前任务实例对应的 RTMP 推流地址，检测到异常后通过固定回调接口上报告警，同时持续推送带标注视频流；任务结束后平台调用停止接口终止检测
当前开放检测类型	`fire_detection`、`bag_detection`、`no_helmet_detection`

视频流检测任务按 instanceId 作为业务主关联键；启动请求、停止请求与告警回调中的 instanceId 必须一致，用于将算法告警与当前巡逻任务实例准确关联。
按 API 设计规范，任务控制接口使用 analysis 模块、资源复数与动作子路径风格；算法类型获取接口使用 GET 查询开放目录；算法侧应将 reportUrl 配置为固定回调接口的完整地址。
若平台存在统一网关域名，则完整回调地址建议为：https://{domain}/api/v1/analysis/video-stream-callbacks/create。
RTMP 推流地址由算法侧在启动接口成功响应中返回；其中 streamKey 固定使用当前 instanceId，即推流地址格式为 rtmp://{host}:{port}/drtm/{instanceId}。
任务结束后，平台应显式调用停止接口；算法侧在成功停止后不应继续对该 instanceId 推送新告警或持续推流。

3.2 视频流检测类型获取接口定义

3.2.1 接口基础信息

配置项	详情
接口名称	视频流检测类型获取接口
接口路径	`/api/v1/analysis/video-stream-detect-types`
请求方法	`GET`
接口描述	查询当前开放的视频流检测算法类型目录，供平台在配置或发起任务前拉取可用检测项

路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 video-stream-detect-types。
返回结果采用扁平数组结构，每个元素包含 item 与 itemDesc，用于表达一个可直接下发到视频流检测任务的检测类型。
当前版本仅返回已开放的视频流检测类型，不返回未发布、灰度中或内部测试类型。

3.2.2 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "item": "fire_detection",
            "itemDesc": "火焰检测"
        },
        {
            "item": "bag_detection",
            "itemDesc": "遗弃物检测"
        },
        {
            "item": "no_helmet_detection",
            "itemDesc": "未戴安全帽检测"
        }
    ]
}

3.2.3 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 查询成功，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data`	Array	已开放的视频流检测类型列表
`data.item`	String	检测类型编码，可用于标识具体视频流检测能力
`data.itemDesc`	String	检测类型中文描述，用于前端展示或人工配置时的可读名称

3.2.4 当前开放检测类型

`item`	`itemDesc`	说明
`fire_detection`	火焰检测	用于识别视频流中的火焰异常
`bag_detection`	遗弃物检测	用于识别视频流中的遗弃物异常
`no_helmet_detection`	未戴安全帽检测	用于识别视频流中未佩戴安全帽的人头目标

3.3 视频流检测启动接口定义

3.3.1 接口基础信息

配置项	详情
接口名称	视频流检测启动接口
接口路径	`/api/v1/analysis/video-stream-tasks/start`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	平台侧下发待检测视频流并启动当前任务实例对应的视频流检测任务

路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 video-stream-tasks，动作为 start。
启动请求中的 instanceId 为当前巡逻任务实例唯一标识，算法侧后续告警回调必须原样带回该字段。
当前版本一个启动请求对应一个视频流检测任务实例；如需检测多路视频流，应逐路发起启动请求。

3.3.2 请求示例

json

{
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "instanceId": "PATROL-INSTANCE-20260424-0001",
    "videoStreamUrl": "rtsp://192.168.1.100/live/robot-camera-main"
}

3.3.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	启动请求唯一标识，用于链路追踪，建议使用 UUID
`instanceId`	String	是	当前任务实例 ID；算法告警回调与停止请求均使用该字段关联同一检测任务
`videoStreamUrl`	String	是	需要检测的视频流地址；可为 RTSP/RTMP 等双方约定协议地址，需保证算法服务可访问

3.3.4 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": {
        "requestId": "550e8400-e29b-41d4-a716-446655440000",
        "instanceId": "PATROL-INSTANCE-20260424-0001",
        "rtmpPushUrl": "rtmp://10.10.10.20:1935/drtm/PATROL-INSTANCE-20260424-0001"
    }
}

3.3.5 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 启动请求已成功受理，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data.requestId`	String	与请求传入的 `requestId` 完全一致，用于链路匹配
`data.instanceId`	String	与请求传入的 `instanceId` 完全一致，表示已受理的检测任务实例
`data.rtmpPushUrl`	String	算法侧返回的 RTMP 推流地址；`streamKey` 固定为当前 `instanceId`

3.4 视频流检测停止接口定义

3.4.1 接口基础信息

配置项	详情
接口名称	视频流检测停止接口
接口路径	`/api/v1/analysis/video-stream-tasks/stop`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	平台侧在视频流检测任务结束时调用该接口，要求算法侧停止指定任务实例的视频流检测

停止接口使用 instanceId 作为主停止条件；如同一任务存在多个控制请求，以最新一次有效启动后的 instanceId 状态为准。
平台在任务完成、任务取消或明确不再需要检测时，都应调用停止接口释放算法资源。

3.4.2 请求示例

json

{
    "requestId": "9e0c7b2e-4f65-4c82-8f63-0bc4f9d3857f",
    "instanceId": "PATROL-INSTANCE-20260424-0001"
}

3.4.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	停止请求唯一标识，用于链路追踪，建议使用 UUID
`instanceId`	String	是	当前任务实例 ID；算法侧根据该字段停止对应检测任务

3.4.4 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": {
        "requestId": "9e0c7b2e-4f65-4c82-8f63-0bc4f9d3857f",
        "instanceId": "PATROL-INSTANCE-20260424-0001"
    }
}

3.4.5 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 停止请求已成功受理，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data.requestId`	String	与请求传入的 `requestId` 完全一致，用于链路匹配
`data.instanceId`	String	与请求传入的 `instanceId` 完全一致，表示已受理停止的检测任务实例

3.5 视频流检测回调接口定义

3.5.1 接口基础信息

配置项	详情
接口名称	视频流检测回调接口
接口路径	`/api/v1/analysis/video-stream-callbacks/create`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	检测到异常后，算法侧按批次回调视频流检测结果；回调中必须带回启动时下发的任务实例 ID

回调接口由平台侧提供，算法侧通过 reportUrl 配置完整回调地址。
路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 video-stream-callbacks，写操作使用 POST .../create。
请求体 / 响应体字段统一使用 camelCase。

3.5.2 请求示例

json

{
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "instanceId": "PATROL-INSTANCE-20260424-0001",
    "resultsList": [
        {
            "objectId": "1212",
            "results": [
                {
                    "type": "fire_detection",
                    "value": "1",
                    "code": "2000",
                    "resImageUrl": "detect-results/result_1745318400.jpg",
                    "pos": [],
                    "conf": 1.0,
                    "desc": "fire_detection"
                },
                {
                    "type": "no_helmet_detection",
                    "value": "1",
                    "code": "2000",
                    "resImageUrl": "detect-results/result_1745318400.jpg",
                    "pos": [],
                    "conf": 1.0,
                    "desc": "no_helmet_detection"
                }
            ]
        }
    ]
}

3.5.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	启动请求唯一标识；建议与启动接口中的 `requestId` 保持一致，便于链路追踪
`instanceId`	String	是	当前任务实例 ID；必须与启动接口中的 `instanceId` 完全一致，用于将告警结果关联到具体任务实例
`resultsList`	Array	是	结果列表；当前实现固定包含一个对象
`resultsList.objectId`	String	是	检测对象 ID；当前实现固定为 `1212`
`resultsList.results`	Array	是	检测结果列表；根据实际检测到的异常类型动态生成
`results.type`	String	是	异常类型，取值见“4.5.4 检测类型枚举”
`results.value`	String	是	检测值；当前实现固定为 `1`，表示本次检测命中异常
`results.code`	String	是	结果码；当前实现固定为 `2000`，严格复用 `AnalysisResultCodeEnum`
`results.resImageUrl`	String	否	告警图路径，表示对象存储中的告警图对象路径，使用 S3 协议
`results.pos`	Array	否	检测框位置；当前实现固定返回空数组
`results.conf`	Number	否	置信度；当前实现固定为 `1.0`
`results.desc`	String	是	描述信息；当前实现与 `type` 保持一致

3.5.4 检测类型枚举

`type` 取值	触发条件	检测逻辑
`fire_detection`	检测到火焰	`fire_bag` 模型 `cls=0`
`bag_detection`	检测到遗弃物	`fire_bag` 模型 `cls=1`
`no_helmet_detection`	检测到未戴安全帽的人头	`head_aqm` 模型 `cls=0` 且存在行人框

3.5.5 响应约定

平台侧成功处理回调后，应返回 HTTP 200 与统一 Result<null> 响应体，例如：

json

{
    "code": 200,
    "message": "success",
    "data": null
}

当请求体缺少必填字段、字段格式非法或枚举值不受支持时，建议返回 HTTP 400，响应体示例如下：

json

{
    "code": 40001,
    "message": "参数校验失败",
    "data": null
}

当平台处理过程中发生内部异常时，建议返回 HTTP 500，响应体示例如下：

json

{
    "code": 50000,
    "message": "服务器内部错误",
    "data": null
}

当前实现会记录回调响应内容；是否重试由算法侧按自身重试策略决定。
当前 HTTP 回调调用超时时间固定为 10s。

3.5.6 触发时机与节流规则

平台侧按回调接收告警结果，不依赖算法内部节流参数。
算法侧可按实现需要维护节流策略（例如告警去重、时间间隔控制），但该策略属于算法内部实现细节，不作为平台接口契约字段。
平台对接重点是：能够稳定接收“检测到异常”时触发的回调请求，并基于 instanceId 将告警结果准确归属到对应任务实例。

3.6 RTMP推流接口定义

3.6.1 接口基础信息

配置项	详情
接口名称	视频流 RTMP 推流接口
推流地址	`rtmp://{host}:{port}/drtm/{instanceId}`
协议	`RTMP`
视频编码	`H.264 (libx264)`
封装格式	`FLV`
接口描述	算法侧在启动接口受理成功后返回对应 RTMP 地址，并持续推送带 AI 标注的视频流，供后端或流媒体服务实时消费

3.6.2 推流参数

参数	值	说明
分辨率	`1280×720`	当前实现硬编码
帧率	`15 fps`	来自 `fps` 配置
编码格式	`H.264 (libx264)`	软编码
码率	`1200k`	固定码率
像素格式	`yuv420p`	标准兼容格式
预设	`superfast`	编码速度优先
调优	`zerolatency`	低延迟
GOP	`10`	关键帧间隔 10 帧
封装格式	`FLV`	RTMP 标准封装格式

3.6.3 推流内容

原始视频帧与 AI 检测框标注一起输出。
当前检测框颜色映射如下：

检测对象	标注颜色
火焰	`(0, 255, 0)`
遗弃物	`(0, 0, 255)`
人头	`(255, 0, 0)`
安全帽	`(0, 255, 255)`

3.6.4 接收端要求

接收方需部署 RTMP 服务器（如 Nginx-RTMP、SRS、Red5），监听端口按实际部署配置。
RTMP 服务需接收路径 /drtm/{instanceId} 的持续推流。
instanceId 直接作为单路视频流的 streamKey，由算法侧在启动成功后拼装完整 rtmpPushUrl 返回平台。
对同一 instanceId，推流生命周期应与检测任务生命周期保持一致；任务停止后应终止对应推流。

3.7 结果码枚举复用规范

说明：本节枚举为视频流告警结果项 results[].code 的业务结果码，不等同于 HTTP 层状态码。

枚举值	编码	视频流检测场景适用说明
`SUCCESS`	`2000`	当前版本已上报的异常检测结果统一使用该编码，表示异常项已成功识别并写入 `results[]`

说明 1：当前版本仅在检测到异常时上报告警结果，不单独定义“未命中异常”的结果项。

说明 2：若后续需要上报视频流检测过程中的取帧失败、分析失败等异常结果，仍须复用附录中的既有结果码，禁止新增自定义编码。

4. VLM算法接口定义

4.1 接口基础信息

配置项	详情
接口名称	VLM算法接口
接口组成	启动接口 + 停止接口 + HTTP 回调接口 + RTMP 实时推流 + 配置动态更新接口
启动接口路径	`/api/v1/analysis/vlm-video-stream-tasks/start`
停止接口路径	`/api/v1/analysis/vlm-video-stream-tasks/stop`
配置更新接口路径	`/api/v1/analysis/vlm-video-stream-tasks/update`
HTTP 回调路径	`/api/v1/analysis/vlm-video-stream-callbacks/create`
HTTP 请求方法	`POST`
RTMP 推流地址	启动成功后由算法侧返回，格式为 `rtmp://{host}:{port}/drtm/{instanceId}`
接口描述	平台侧下发待分析视频流、任务实例 ID 与自然语言提示词；算法侧受理成功后返回当前任务实例对应的 RTMP 推流地址，识别到符合提示词描述的目标后通过固定回调接口上报结果，同时持续推送带标注视频流；任务运行期间可通过配置动态更新接口在线调整提示词或扩展参数；任务结束后平台调用停止接口终止分析

VLM 接口整体交互模式、返回结构、回调响应约定与 RTMP 推流规范均复用第 4 章视频流检测接口定义。
与视频流检测接口唯一的协议差异是：VLM 启动接口必须新增 prompt 字段，用于描述本次视频流分析目标，例如“检查视频流中的某个缺陷”。
为避免与规则型视频流检测任务混用，VLM 接口使用独立路径：vlm-video-stream-tasks 与 vlm-video-stream-callbacks。
VLM 任务同样按 instanceId 作为业务主关联键；启动请求、停止请求、配置更新请求与回调中的 instanceId 必须一致。
VLM 任务运行期间，平台可通过配置动态更新接口在线调整 prompt 提示词等运行参数，无需停止后重新启动任务。

4.2 VLM分析启动接口定义

4.2.1 接口基础信息

配置项	详情
接口名称	VLM分析启动接口
接口路径	`/api/v1/analysis/vlm-video-stream-tasks/start`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	平台侧下发待分析视频流、当前任务实例 ID 与提示词，启动当前任务实例对应的 VLM 视频流分析任务

路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 vlm-video-stream-tasks，动作为 start。
启动请求中的 instanceId 为当前巡逻任务实例唯一标识，算法侧后续回调必须原样带回该字段。
prompt 为本次 VLM 分析的核心控制参数，建议使用明确、可执行、可观察的自然语言描述，避免歧义。
当前版本一个启动请求对应一个 VLM 视频流分析任务实例；如需同时分析多路视频流，应逐路发起启动请求。

4.2.2 请求示例

json

{
    "requestId": "650e8400-e29b-41d4-a716-446655440000",
    "instanceId": "PATROL-INSTANCE-20260427-0001",
    "videoStreamUrl": "rtsp://192.168.1.100/live/robot-camera-main",
    "prompt": "检查视频流中的某个缺陷"
}

4.2.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	启动请求唯一标识，用于链路追踪，建议使用 UUID
`instanceId`	String	是	当前任务实例 ID；算法回调与停止请求均使用该字段关联同一分析任务
`videoStreamUrl`	String	是	需要分析的视频流地址；可为 RTSP/RTMP 等双方约定协议地址，需保证算法服务可访问
`prompt`	String	是	VLM 提示词，用于描述本次视频流分析目标，例如“检查视频流中的某个缺陷”

4.2.4 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": {
        "requestId": "650e8400-e29b-41d4-a716-446655440000",
        "instanceId": "PATROL-INSTANCE-20260427-0001",
        "rtmpPushUrl": "rtmp://10.10.10.20:1935/drtm/PATROL-INSTANCE-20260427-0001"
    }
}

4.2.5 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 启动请求已成功受理，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data.requestId`	String	与请求传入的 `requestId` 完全一致，用于链路匹配
`data.instanceId`	String	与请求传入的 `instanceId` 完全一致，表示已受理的 VLM 分析任务实例
`data.rtmpPushUrl`	String	算法侧返回的 RTMP 推流地址；`streamKey` 固定为当前 `instanceId`

4.3 VLM分析停止接口定义

4.3.1 接口基础信息

配置项	详情
接口名称	VLM分析停止接口
接口路径	`/api/v1/analysis/vlm-video-stream-tasks/stop`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	平台侧在 VLM 视频流分析任务结束时调用该接口，要求算法侧停止指定任务实例的 VLM 分析

停止接口使用 instanceId 作为主停止条件；如同一任务存在多个控制请求，以最新一次有效启动后的 instanceId 状态为准。
平台在任务完成、任务取消或明确不再需要分析时，都应调用停止接口释放算法资源。

4.3.2 请求示例

json

{
    "requestId": "7c0c7b2e-4f65-4c82-8f63-0bc4f9d3857f",
    "instanceId": "PATROL-INSTANCE-20260427-0001"
}

4.3.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	停止请求唯一标识，用于链路追踪，建议使用 UUID
`instanceId`	String	是	当前任务实例 ID；算法侧根据该字段停止对应 VLM 分析任务

4.3.4 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": {
        "requestId": "7c0c7b2e-4f65-4c82-8f63-0bc4f9d3857f",
        "instanceId": "PATROL-INSTANCE-20260427-0001"
    }
}

4.3.5 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 停止请求已成功受理，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data.requestId`	String	与请求传入的 `requestId` 完全一致，用于链路匹配
`data.instanceId`	String	与请求传入的 `instanceId` 完全一致，表示已受理停止的 VLM 分析任务实例

4.4 VLM分析回调接口定义

4.4.1 接口基础信息

配置项	详情
接口名称	VLM分析回调接口
接口路径	`/api/v1/analysis/vlm-video-stream-callbacks/create`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	识别到符合提示词描述的目标后，算法侧按批次回调 VLM 视频流分析结果；回调中必须带回启动时下发的任务实例 ID

回调接口由平台侧提供，算法侧通过 reportUrl 配置完整回调地址。
路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 vlm-video-stream-callbacks，写操作使用 POST .../create。
请求体 / 响应体字段统一使用 camelCase；除路径和业务语义外，整体结构与视频流检测回调接口保持一致。

4.4.2 请求示例

json

{
    "requestId": "650e8400-e29b-41d4-a716-446655440000",
    "instanceId": "PATROL-INSTANCE-20260427-0001",
    "resultsList": [
        {
            "objectId": "1212",
            "results": [
                {
                    "type": "vlm_detection",
                    "value": "1",
                    "code": "2000",
                    "resImageUrl": "detect-results/result_1745318400.jpg",
                    "pos": [],
                    "conf": 1.0,
                    "desc": "检查视频流中的某个缺陷"
                }
            ]
        }
    ]
}

4.4.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	启动请求唯一标识；建议与启动接口中的 `requestId` 保持一致，便于链路追踪
`instanceId`	String	是	当前任务实例 ID；必须与启动接口中的 `instanceId` 完全一致，用于将分析结果关联到具体任务实例
`resultsList`	Array	是	结果列表；当前实现固定包含一个对象
`resultsList.objectId`	String	是	检测对象 ID；当前实现固定为 `1212`
`resultsList.results`	Array	是	分析结果列表；根据实际识别到的提示词命中目标动态生成
`results.type`	String	是	结果类型；VLM 场景当前固定为 `vlm_detection`
`results.value`	String	是	检测值；当前实现固定为 `1`，表示本次分析命中提示词描述的目标
`results.code`	String	是	结果码；当前实现固定为 `2000`，严格复用 `AnalysisResultCodeEnum`
`results.resImageUrl`	String	否	告警图路径，表示对象存储中的告警图对象路径，使用 S3 协议
`results.pos`	Array	否	检测框位置；当前实现固定返回空数组
`results.conf`	Number	否	置信度；当前实现固定为 `1.0`
`results.desc`	String	是	描述信息；建议原样返回启动接口中的 `prompt` 或对其做等价归一化描述

4.4.4 响应约定

平台侧成功处理回调后，应返回 HTTP 200 与统一 Result<null> 响应体，例如：

json

{
    "code": 200,
    "message": "success",
    "data": null
}

当请求体缺少必填字段、字段格式非法或枚举值不受支持时，建议返回 HTTP 400，响应体示例如下：

json

{
    "code": 40001,
    "message": "参数校验失败",
    "data": null
}

当平台处理过程中发生内部异常时，建议返回 HTTP 500，响应体示例如下：

json

{
    "code": 50000,
    "message": "服务器内部错误",
    "data": null
}

当前实现会记录回调响应内容；是否重试由算法侧按自身重试策略决定。
当前 HTTP 回调调用超时时间固定为 10s。

4.4.5 触发时机与节流规则

平台侧按回调接收分析结果，不依赖算法内部节流参数。
算法侧可按实现需要维护节流策略（例如相同提示词结果去重、时间间隔控制），但该策略属于算法内部实现细节，不作为平台接口契约字段。
平台对接重点是：能够稳定接收“命中提示词描述目标”时触发的回调请求，并基于 instanceId 将结果准确归属到对应任务实例。

4.5 VLM RTMP推流接口定义

4.5.1 接口基础信息

配置项	详情
接口名称	VLM 视频流 RTMP 推流接口
推流地址	`rtmp://{host}:{port}/drtm/{instanceId}`
协议	`RTMP`
视频编码	`H.264 (libx264)`
封装格式	`FLV`
接口描述	算法侧在启动接口受理成功后返回对应 RTMP 地址，并持续推送带 VLM 标注的视频流，供后端或流媒体服务实时消费

4.5.2 推流参数

参数	值	说明
分辨率	`1280×720`	当前实现硬编码
帧率	`15 fps`	来自 `fps` 配置
编码格式	`H.264 (libx264)`	软编码
码率	`1200k`	固定码率
像素格式	`yuv420p`	标准兼容格式
预设	`superfast`	编码速度优先
调优	`zerolatency`	低延迟
GOP	`10`	关键帧间隔 10 帧
封装格式	`FLV`	RTMP 标准封装格式

4.5.3 推流内容

原始视频帧与 VLM 分析标注一起输出。
标注内容由提示词命中的目标和算法实现决定，建议在画面中同时展示命中框、提示词摘要与必要的置信度信息。

4.5.4 接收端要求

接收方需部署 RTMP 服务器（如 Nginx-RTMP、SRS、Red5），监听端口按实际部署配置。
RTMP 服务需接收路径 /drtm/{instanceId} 的持续推流。
instanceId 直接作为单路视频流的 streamKey，由算法侧在启动成功后拼装完整 rtmpPushUrl 返回平台。
对同一 instanceId，推流生命周期应与 VLM 分析任务生命周期保持一致；任务停止后应终止对应推流。

4.6 结果码枚举复用规范

说明：本节枚举为 VLM 分析结果项 results[].code 的业务结果码，不等同于 HTTP 层状态码。

枚举值	编码	VLM 场景适用说明
`SUCCESS`	`2000`	当前版本已上报的 VLM 提示词命中结果统一使用该编码，表示异常项或关注项已成功识别并写入 `results[]`

说明 1：当前版本仅在检测到符合提示词描述的目标时上报结果，不单独定义“未命中提示词”的结果项。

说明 2：若后续需要上报 VLM 分析过程中的取帧失败、分析失败等异常结果，仍须复用附录中的既有结果码，禁止新增自定义编码。

4.7 VLM配置动态更新接口定义

4.7.1 接口基础信息

配置项	详情
接口名称	VLM配置动态更新接口
接口路径	`/api/v1/analysis/vlm-video-stream-tasks/update`
请求方法	`POST`
`Content-Type`	`application/json`
接口描述	VLM 任务运行期间，平台侧可通过该接口在线更新当前任务实例的提示词或扩展配置参数，算法侧在收到更新后即时生效，无需停止并重新启动任务

路径遵循 API 设计规范：/api/v1/{module}/...，其中 {module}=analysis，资源名使用复数 vlm-video-stream-tasks，动作为 update。
更新请求中的 instanceId 必须为当前正在运行的 VLM 任务实例 ID；算法侧校验任务存在且状态可更新后返回受理结果。
当前版本仅支持在任务运行期间调用该接口；任务已停止或未启动时调用将返回受理失败。
更新操作不会影响当前 RTMP 推流链路；streamKey 与推流地址保持与启动时一致。

4.7.2 请求示例

json

{
    "requestId": "8d1e7b2e-4f65-4c82-8f63-0bc4f9d3857f",
    "instanceId": "PATROL-INSTANCE-20260427-0001",
    "prompt": "更新后的提示词描述，例如检查视频流中是否出现烟雾",
    "report_interval": 5
}

4.7.3 字段说明

字段	类型	必填	说明
`requestId`	String	是	更新请求唯一标识，用于链路追踪，建议使用 UUID
`instanceId`	String	是	当前任务实例 ID；必须与启动接口中的 `instanceId` 完全一致，算法侧根据该字段定位运行中的 VLM 分析任务
`prompt`	String	否	更新后的 VLM 提示词，用于替换当前运行任务的分析目标描述；不传则不更新提示词
`report_interval`	Integer	否	上报间隔（秒），控制 VLM 分析结果回调的最小时间间隔；不传则沿用当前生效值

说明：prompt 与 report_interval 至少提供一个，否则视为无效更新请求。

4.7.4 响应示例

json

{
    "code": 200,
    "message": "success",
    "data": {
        "requestId": "8d1e7b2e-4f65-4c82-8f63-0bc4f9d3857f",
        "instanceId": "PATROL-INSTANCE-20260427-0001",
        "report_interval": 5
    }
}

4.7.5 响应字段说明

字段	类型	说明
`code`	Integer	统一业务状态码，`200` = 配置更新已成功受理，失败返回 `500`
`message`	String	统一响应描述，成功固定返回 `success`，失败返回错误详情
`data.requestId`	String	与请求传入的 `requestId` 完全一致，用于链路匹配
`data.instanceId`	String	与请求传入的 `instanceId` 完全一致，表示已受理配置更新的 VLM 分析任务实例
`data.report_interval`	Integer	本次更新生效的上报间隔（秒），回显请求传入的值或当前实际生效值

4.7.6 生效时机与注意事项

算法侧收到有效更新请求后应立即应用新配置；提示词更新后，后续视频帧分析按新提示词执行。
配置更新前的回调结果不受影响；更新后新产生的回调结果中 desc 字段建议反映更新后的提示词内容。
同一任务实例多次调用更新接口时，以最近一次成功受理的配置为准。
若更新时任务已停止或 instanceId 不存在，算法侧应返回受理失败（code=500），并在 message 中明确错误原因。

5. 附录：全量算法结果码枚举

枚举值	编码	描述
`SUCCESS`	`2000`	正确
`GET_IMAGE_ERROR`	`2001`	未能获取到图像数据
`ANALYSIS_IMAGE_ERROR`	`2002`	算法本身分析过程出错
`IMAGE_NO_METER`	`2003`	画面中没有表计
`IMAGE_NO_TARGET_DEVICE`	`2004`	画面中没有对应状态识别设备

算法分析接口文档 ​

文档属性 ​

1. 概述 ​

2. 通用规范 ​

3. 视频流检测接口定义 ​

3.1 接口概览 ​

3.2 视频流检测类型获取接口定义 ​

3.2.1 接口基础信息 ​

3.2.2 响应示例 ​

3.2.3 响应字段说明 ​

3.2.4 当前开放检测类型 ​

3.3 视频流检测启动接口定义 ​

3.3.1 接口基础信息 ​

3.3.2 请求示例 ​

3.3.3 字段说明 ​

3.3.4 响应示例 ​

3.3.5 响应字段说明 ​

3.4 视频流检测停止接口定义 ​

3.4.1 接口基础信息 ​

3.4.2 请求示例 ​

3.4.3 字段说明 ​

3.4.4 响应示例 ​

3.4.5 响应字段说明 ​

3.5 视频流检测回调接口定义 ​

3.5.1 接口基础信息 ​

3.5.2 请求示例 ​

3.5.3 字段说明 ​

3.5.4 检测类型枚举 ​

3.5.5 响应约定 ​

3.5.6 触发时机与节流规则 ​

3.6 RTMP推流接口定义 ​

3.6.1 接口基础信息 ​

3.6.2 推流参数 ​

3.6.3 推流内容 ​

3.6.4 接收端要求 ​

3.7 结果码枚举复用规范 ​

4. VLM算法接口定义 ​

4.1 接口基础信息 ​

4.2 VLM分析启动接口定义 ​

4.2.1 接口基础信息 ​

4.2.2 请求示例 ​

4.2.3 字段说明 ​

4.2.4 响应示例 ​

4.2.5 响应字段说明 ​

4.3 VLM分析停止接口定义 ​

4.3.1 接口基础信息 ​

4.3.2 请求示例 ​

4.3.3 字段说明 ​

4.3.4 响应示例 ​

4.3.5 响应字段说明 ​

4.4 VLM分析回调接口定义 ​

4.4.1 接口基础信息 ​

4.4.2 请求示例 ​

4.4.3 字段说明 ​

4.4.4 响应约定 ​

4.4.5 触发时机与节流规则 ​

4.5 VLM RTMP推流接口定义 ​

4.5.1 接口基础信息 ​

4.5.2 推流参数 ​

4.5.3 推流内容 ​

4.5.4 接收端要求 ​

4.6 结果码枚举复用规范 ​

4.7 VLM配置动态更新接口定义 ​

4.7.1 接口基础信息 ​

4.7.2 请求示例 ​

4.7.3 字段说明 ​

4.7.4 响应示例 ​

4.7.5 响应字段说明 ​

4.7.6 生效时机与注意事项 ​

5. 附录：全量算法结果码枚举 ​

算法分析接口文档

文档属性

1. 概述

2. 通用规范

3. 视频流检测接口定义

3.1 接口概览

3.2 视频流检测类型获取接口定义

3.2.1 接口基础信息

3.2.2 响应示例

3.2.3 响应字段说明

3.2.4 当前开放检测类型

3.3 视频流检测启动接口定义

3.3.1 接口基础信息

3.3.2 请求示例

3.3.3 字段说明

3.3.4 响应示例

3.3.5 响应字段说明

3.4 视频流检测停止接口定义

3.4.1 接口基础信息

3.4.2 请求示例

3.4.3 字段说明

3.4.4 响应示例

3.4.5 响应字段说明

3.5 视频流检测回调接口定义

3.5.1 接口基础信息

3.5.2 请求示例

3.5.3 字段说明

3.5.4 检测类型枚举

3.5.5 响应约定

3.5.6 触发时机与节流规则

3.6 RTMP推流接口定义

3.6.1 接口基础信息

3.6.2 推流参数

3.6.3 推流内容

3.6.4 接收端要求

3.7 结果码枚举复用规范

4. VLM算法接口定义

4.1 接口基础信息

4.2 VLM分析启动接口定义

4.2.1 接口基础信息

4.2.2 请求示例

4.2.3 字段说明

4.2.4 响应示例

4.2.5 响应字段说明

4.3 VLM分析停止接口定义

4.3.1 接口基础信息

4.3.2 请求示例

4.3.3 字段说明

4.3.4 响应示例

4.3.5 响应字段说明

4.4 VLM分析回调接口定义

4.4.1 接口基础信息

4.4.2 请求示例

4.4.3 字段说明

4.4.4 响应约定

4.4.5 触发时机与节流规则

4.5 VLM RTMP推流接口定义

4.5.1 接口基础信息

4.5.2 推流参数

4.5.3 推流内容

4.5.4 接收端要求

4.6 结果码枚举复用规范

4.7 VLM配置动态更新接口定义

4.7.1 接口基础信息

4.7.2 请求示例

4.7.3 字段说明

4.7.4 响应示例

4.7.5 响应字段说明

4.7.6 生效时机与注意事项

5. 附录：全量算法结果码枚举