AI 算法平台外部 API 接入说明

本文是面向外部调用方的公开镜像，源文件为仓库 docs/api-integration.md；服务地址：https://aiprovider.agenticskills.dev。

本文面向通过 HTTP API 调用本平台的外部调用方（如视频平台），描述图片隐患识别服务的接口契约。服务采用异步 Job：调用方提交一张图片，平台返回 jobId，分析完成后由调用方轮询或接收回调。

1. 鉴权与公共规则

所有业务接口使用 Authorization: Bearer <token>。
调用方身份由 Bearer Token 认证；V1 为单一调用方，请求和查询都不传 clientId。
请求 capturedAt 必须是带 Z 或 UTC offset 的 RFC 3339 字符串。
响应时间统一为 UTC（Z）。
建议调用方传 X-Request-Id；未传时 Provider 自动生成，响应头和正文都会返回。
图片以 Base64 传入（不含 data: 前缀），支持 JPEG/PNG/WebP。

2. 查询能力

GET /openapi/v1/capabilities
Authorization: Bearer <token>

调用方应从 capabilities 获取当前 catalogVersion、默认隐患 codes 和可调用定义，不在自身代码中固定模型名称或实现模式。

当前能力目录（实际响应示例，目录版本以后端返回为准）：

{
  "requestId": "req_...",
  "schemaVersion": "1.0",
  "catalogVersion": "2026.08.01-1",
  "defaultAnalysisMode": "LLM",
  "defaultHazardCodes": [
    "UNPROTECTED_EDGE",
    "UNSAFE_CLIMBING",
    "UNSAFE_WORK_PLATFORM",
    "UNPROTECTED_OPENING",
    "UNSAFE_CROSS_LEVEL_WORK",
    "NO_HELMET",
    "NO_SAFETY_HARNESS"
  ],
  "analysisModes": [
    {
      "mode": "LITE",
      "supportedHazardCodes": ["NO_HELMET", "NO_REFLECTIVE_VEST"]
    },
    {
      "mode": "HYBRID",
      "supportedHazardCodes": ["NO_HELMET", "NO_REFLECTIVE_VEST"]
    },
    {
      "mode": "LLM",
      "supportedHazardCodes": ["UNPROTECTED_EDGE", "UNSAFE_CLIMBING", "UNSAFE_WORK_PLATFORM", "UNPROTECTED_OPENING", "UNSAFE_CROSS_LEVEL_WORK", "NO_HELMET", "NO_SAFETY_HARNESS", "NO_REFLECTIVE_VEST", "DISORDERLY_MATERIAL_STORAGE"]
    }
  ],
  "hazards": [
    {"code": "UNPROTECTED_EDGE", "name": "临边防护缺失", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别楼层、屋顶、阳台、基坑等临边区域的防护缺失或明显失效", "status": "BETA"},
    {"code": "UNSAFE_CLIMBING", "name": "攀登设施或方式不安全", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别梯子、脚手架、钢构件等攀登设施或使用方式存在的明显风险", "status": "BETA"},
    {"code": "UNSAFE_WORK_PLATFORM", "name": "作业平台防护不足", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别脚手架、移动平台或设备平台的作业面和防护设施不足", "status": "BETA"},
    {"code": "UNPROTECTED_OPENING", "name": "洞口防护缺失", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别预留洞口、电梯井口、楼梯口、坑井等位置的防护缺失", "status": "BETA"},
    {"code": "UNSAFE_CROSS_LEVEL_WORK", "name": "垂直交叉作业防护不足", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别上下作业面重叠且缺少隔离防护的物体打击风险", "status": "BETA"},
    {"code": "NO_HELMET", "name": "未佩戴安全帽", "categoryCode": "PERSONAL_PROTECTION", "categoryName": "个人防护", "description": "识别施工或危险区域内人员未佩戴安全帽的情况", "status": "BETA"},
    {"code": "NO_SAFETY_HARNESS", "name": "高处作业未正确使用安全带", "categoryCode": "WORK_AT_HEIGHT", "categoryName": "高处作业", "description": "识别高处作业人员未佩戴或未有效系挂安全带", "status": "BETA"},
    {"code": "NO_REFLECTIVE_VEST", "name": "未穿反光警示服", "categoryCode": "PERSONAL_PROTECTION", "categoryName": "个人防护", "description": "识别需要提高可见性的施工区域内人员未穿反光警示服", "status": "BETA"},
    {"code": "DISORDERLY_MATERIAL_STORAGE", "name": "材料堆放存在安全风险", "categoryCode": "SITE_HOUSEKEEPING", "categoryName": "文明施工", "description": "识别材料明显倾斜、不稳定或占用通道造成的安全风险", "status": "BETA"}
  ]
}

说明：

defaultHazardCodes 是提交时省略 hazardCodes 使用的默认检查项（当前 7 项）。
defaultAnalysisMode 是省略 analysisMode 时使用的服务端默认档位（当前为 LLM，由部署配置控制）。
analysisModes 是当前可用的分析档位及其支持的隐患范围；档位不绑定具体模型名称，LITE 为轻量模型直接出结果，LLM 为大模型单跑，HYBRID 为轻量模型检出后由大模型复核。YOLO 模型未配置时 LITE/HYBRID 不返回。
NO_REFLECTIVE_VEST、DISORDERLY_MATERIAL_STORAGE 未默认开启，需要显式在 hazardCodes 中指定。
目录版本、条目和状态以后端返回为准，调用方不要固定目录版本。

3. 提交图片 Job

POST /openapi/v1/image-inference/jobs
Authorization: Bearer <token>
Content-Type: application/json

{
  "capturedAt": "2024-08-15T14:58:00+08:00",
  "analysisMode": "LLM",
  "image": {
    "contentType": "image/png",
    "base64": "<图片 Base64，不含 data URL 前缀>"
  },
  "hazardCodes": [
    "UNSAFE_CLIMBING",
    "UNSAFE_WORK_PLATFORM",
    "UNPROTECTED_EDGE",
    "NO_SAFETY_HARNESS"
  ],
  "callbackUrl": "https://caller.example.com/callbacks/ai-result",
  "meta": {
    "cameraId": "camera-001"
  }
}

analysisMode、hazardCodes 和 callbackUrl 均可省略：analysisMode 省略时使用服务端默认档位（初始 LLM），hazardCodes 省略时使用 capabilities 中的默认检查项，callbackUrl 省略时仅轮询。meta.cameraId 必填（去除首尾空格后 1～128 字符），是调用方的业务摄像头标识；meta 其余字段可省略，整体不超过 4KB。

分析档位

analysisMode 合法值为 LITE、LLM、HYBRID，分别对应“轻量模型直接出结果”“大模型单跑”“轻量模型检出 + 大模型复核”。档位不绑定具体模型名称，平台内部可随时更换实现。档位与 hazardCodes 必须匹配：请求的有效检查项必须全部落在该档位的 supportedHazardCodes 内，否则返回 422 UNSUPPORTED_HAZARD_CODE，details 中带 mode 和 supportedHazardCodes；LITE/HYBRID 省略 hazardCodes 时使用默认检查项与档位支持范围的交集。

受理响应：

HTTP/1.1 202 Accepted
Location: /openapi/v1/image-inference/jobs/job_...

{
  "requestId": "req_...",
  "jobId": "job_...",
  "status": "QUEUED",
  "createdAt": "2026-08-01T18:26:16.619Z"
}

4. 轮询结果

GET /openapi/v1/image-inference/jobs/{jobId}
Authorization: Bearer <token>

QUEUED 和 RUNNING 不含 analysis。成功示例：

耗时与超时预期

从受理到终态通常为几十秒到约 2 分钟：默认 Plus 模型下，简单/负样本画面约 30 秒，复杂多隐患画面约 1.5～2 分钟（实测范围约 28 秒～124 秒）；模型负载升高时可能更慢。
Job 最长排队 600 秒、最长执行 300 秒；超过执行时限会进入 FAILED（例如 MODEL_TIMEOUT）。
提交响应建议按 Retry-After: 2 轮询（2 秒一次）；调用方整体轮询超时建议设置为 240 秒以上。
高峰期排队时间会计入总耗时，调用方应容忍排队导致的延迟。

{
  "requestId": "req_...",
  "jobId": "job_...",
  "status": "SUCCEEDED",
  "capturedAt": "2024-08-15T06:58:00.000Z",
  "createdAt": "2026-08-01T18:26:16.619Z",
  "startedAt": "2026-08-01T18:26:16.883Z",
  "completedAt": "2026-08-01T18:28:16.288Z",
  "analysis": {
    "imageSummary": "建筑施工现场，多名佩戴安全帽的工人在楼层作业面及脚手架区域活动，红圈标注处有一人在脚手架杆件间。",
    "conclusion": "HAZARD_DETECTED",
    "hazards": [
      {
        "code": "UNSAFE_CLIMBING",
        "name": "攀登设施或方式不安全",
        "categoryCode": "WORK_AT_HEIGHT",
        "categoryName": "高处作业",
        "severity": "HIGH",
        "confidence": 0.85,
        "confidenceType": "SEMANTIC_SCORE",
        "description": "红圈处人员正在攀爬或站立在脚手架横杆上，未见专用上下通道。",
        "locationText": "画面右侧红圈处",
        "suggestion": "停止使用不安全攀登设施，改用检查合格且固定可靠的通道并落实防坠措施"
      }
    ],
    "uncertain": [
      {
        "code": "NO_SAFETY_HARNESS",
        "name": "高处作业未正确使用安全带",
        "categoryCode": "WORK_AT_HEIGHT",
        "categoryName": "高处作业",
        "severity": "HIGH",
        "confidence": 0.5,
        "confidenceType": "SEMANTIC_SCORE",
        "description": "受距离和遮挡影响，无法清晰确认是否佩戴并有效系挂安全带。",
        "locationText": "画面右侧红圈处及上方作业面",
        "suggestion": "停止高处作业，正确佩戴并将安全带系挂到可靠锚点后再作业"
      }
    ]
  }
}

建议调用方将 hazards 作为告警候选，将 uncertain 作为人工复核候选，不要合并两者。imageSummary 是客观画面摘要，不替代结构化隐患判断。

失败 Job 只返回 error，例如：

{
  "requestId": "req_...",
  "jobId": "job_...",
  "status": "FAILED",
  "capturedAt": "2024-08-15T06:58:00.000Z",
  "createdAt": "2026-08-01T18:23:20.135Z",
  "startedAt": "2026-08-01T18:23:21.002Z",
  "completedAt": "2026-08-01T18:25:21.408Z",
  "error": {
    "code": "MODEL_TIMEOUT",
    "message": "模型调用超时"
  }
}

5. 回调

callbackUrl 可选；提供时平台在 Job 终态后向该地址投递与轮询相同的结果结构。回调失败不会把推理成功改成 FAILED。回调请求携带的 Bearer Token 由平台侧配置，不接受提交请求传入，请按平台侧提供的信息校验回调来源。

回调地址必须公网可达；正式环境平台会要求 HTTPS 并仅向白名单 Host 投递（联调环境可能临时放宽，正式接入请直接使用 HTTPS 地址）。

6. 错误与受理限制

HTTP	Code	含义
400	`INVALID_REQUEST`	请求字段不合法
401	`UNAUTHORIZED`	Bearer Token 缺失或错误
404	`JOB_NOT_FOUND`	Job 不存在、不属于调用方或已过保留期
413	`IMAGE_TOO_LARGE`	请求体、图片字节或像素超限
415	`UNSUPPORTED_IMAGE_FORMAT`	图片格式不支持
422	`INVALID_IMAGE`	Base64 或图片内容损坏
422	`UNSUPPORTED_HAZARD_CODE`	code 未开放，或超出所选 `analysisMode` 档位的支持范围
429	`RATE_LIMITED`	单 API 默认超过 30 次/60 秒（规则 `CLIENT_WINDOW`），或同一摄像头短于动态策略间隔（规则 `CAMERA_INTERVAL`）；遵循 `Retry-After`，规则见 `details.rule`
503	`SERVICE_BUSY`	排队 Job 达到 20（规则 `QUEUE_CAPACITY`），或外部在途达到动态策略上限（规则 `EXTERNAL_IN_FLIGHT`）

当前部署的受理限制默认值（可由平台运营调整）：

调用方限流：30 次/60 秒（CLIENT_WINDOW）。
同一摄像头（meta.cameraId）最短提交间隔：900 秒（15 分钟），规则 CAMERA_INTERVAL；用于避免同一路视频画面被重复分析，默认值可在平台侧调整。
外部在途 Job 上限：5（规则 EXTERNAL_IN_FLIGHT），达到后请等待在途 Job 完成再提交。
排队 Job 上限：20（规则 QUEUE_CAPACITY）。
HTTP 请求体上限 8 MiB、解码图片上限 5 MiB、最大 1600 万像素、单边最大 4096。

调用方收到 429 时遵循 Retry-After 后再重试；收到 503 时稍后重新提交，不要立即高频重试。

本页由仓库 docs/api-integration.md 生成的公开镜像；接口以实际部署版本为准。