AI验收

功能说明

这是什么

AI 工地验收开放接口:把某个工地一次验收的现场照片/视频,连同验收标准,提交给 AI 做合规检测,返回一份结构化验收报告——每个检查项给出 PASS(合规)/ FAIL(违规)/ MISSING(缺失)/ UNKNOWN(无法判断)、画面证据、整改建议,并附总体结论与评分。

数据怎么传(重要)

1. 一次请求 = 一次验收。请求里 projectId(工地)+ requestId(请求 ID)唯一确定一次验收。不要把不相关的内容拼到一次请求里。
2. requestId 是幂等键(关键)。由调用方为每一次”想计费的验收”生成一个唯一值(如 UUID,自行保存):
   • 重试复用同一个 requestId —— 网络超时、未收到回调等情况重发,服务端按 (projectId, requestId) 识别为同一次,直接返回已存结果,不重跑 AI、不重复计费。
   • 重新验收换一个新 requestId —— 哪怕同一工地、同一天,只要是新的 requestId 就是一次新的分析,会重新计费。
   • 服务端不存在”强制重检”开关:analyze 调一次(新 requestId)就计一次费;只想看历史结果请走 /result(纯读、不计费)。
3. 按”分项”组织 checkItems。验收标准通常拆成若干分项(检查点),每个分项对应 checkItems 里的一条:
   • acceptanceCriteria:该分项的验收标准原文(可带 HTML,服务端自动去标签);
   • medias:属于该分项的照片/视频。
   • AI 对每个分项只依据它自己的 medias 判定,逐项分析后合并成一份报告。所以媒体必须按分项归组——哪些图/视频对应哪个检查点,就放进那个分项的 medias,不要把全部图一股脑塞给一个分项。
   • 即使只有一个检查点,也作为 1 个分项传(checkItems 含 1 条)。
4. 媒体限制:每个分项 ≤ 20 张图片、≤ 5 个视频;单个视频时长 ≤ 5 分钟(由调用方保证);一次请求 ≤ 20 个分项。

调用流程

1. 调 POST /openapi/aiAcceptance/analyze 提交(projectId + requestId + checkItems,可选 callbackUrl)。AI 分析较慢,接口异步受理、立即返回,不会等分析完成。
2. 取结果二选一:
   • 传了 callbackUrl → 分析完成后,结果会 POST 回调到该地址(回调体见「查询 AI 验收结果」的响应结构);
   • 没传 → 用 GET /openapi/aiAcceptance/result?projectId=&requestId= 轮询;分析进行中 status=RUNNING(或 data 为空),完成后 status=SUCCESS 并返回报告。
3. 额度:工地的 AI 验收有额度/次数限制,余量或次数不足时 analyze 对新 requestId 直接返回错误(不受理),错误信息会说明原因(如需更多请联系销售购买)。

鉴权

与其它 openapi 接口一致:header 中携带 timestamp、clientCode、sign。

AI 工地验收分析（异步受理）

接口地址:/openapi/aiAcceptance/analyze

请求方式:POST

请求数据类型:application/json

响应数据类型:*/*

接口描述:

提交一次 AI 验收分析（按分项）。统一异步:接口立即受理并返回,后台按分项依次跑 AI 并计费;传 callbackUrl 则完成后回调,不传则用「查询 AI 验收结果」接口按 工地+requestId 轮询。requestId 为调用方幂等键:同 (projectId, requestId) 重试不重跑 AI、不重复计费;重新验收换新 requestId(会重新计费)。余量不足 / 工地不属于当前租户 / 分项数超过本工地剩余可验次数 / 系统繁忙 时直接返错误。鉴权同其它 openapi(header 携带 timestamp、clientCode、sign)。

媒体限制:单次最多 20 个分项;每个分项最多 20 张图片、5 个视频(服务端校验,超出报错);单个视频时长请控制在 5 分钟以内(由调用方保证,服务端不做时长校验,超长可能导致 AI 分析失败或超时)。

请求示例:

{
  "projectId": 100001,
  "requestId": "a1b2c3d4-2026-0623-muGong-0001",
  "operatorId": 2001,
  "callbackUrl": "https://thirdparty.com/ai/callback",
  "checkItems": [
    {
      "acceptanceCriteria": "轻钢龙骨间距不大于400mm,吊杆无松动",
      "medias": [
        { "type": "image", "url": "https://cdn.thirdparty.com/longgu1.jpg" },
        { "type": "video", "url": "https://cdn.thirdparty.com/longgu.mp4" }
      ]
    },
    {
      "acceptanceCriteria": "墙面瓷砖铺贴平整,空鼓率不超过5%,砖缝宽窄均匀",
      "medias": [
        { "type": "image", "url": "https://cdn.thirdparty.com/cizhuan1.jpg" },
        { "type": "image", "url": "https://cdn.thirdparty.com/cizhuan2.jpg" }
      ]
    }
  ]
}

请求参数:

响应状态:

响应参数:

响应示例:

{
    "code": 0,
    "data": {
        "accepted": true,
        "projectId": 100001,
        "requestId": "a1b2c3d4-2026-0623-muGong-0001",
        "message": "已受理,分析完成后将回调 callbackUrl;也可用 /result 按工地+requestId 查询"
    },
    "message": "",
    "successful": true
}

查询 AI 验收结果

接口地址:/openapi/aiAcceptance/result

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

按 工地+requestId 查询 AI 验收分析结果(纯读,不计费、不触发 AI)。analyze 受理后即有一行 status=RUNNING,完成后变为 SUCCESS/AI_EMPTY/BILLING_BLOCKED;可重复轮询。未命中时 data 为空。也用作 analyze 回调体的结构。

请求参数:

响应状态:

响应参数:

响应示例:

{
    "code": 0,
    "data": {
        "projectId": 100001,
        "requestId": "a1b2c3d4-2026-0623-muGong-0001",
        "status": "SUCCESS",
        "analysisDate": "2026-06-23",
        "billingBlocked": false,
        "billingErrorCode": "",
        "errorMsg": "",
        "usedTimes": 1,
        "maxTimes": 5,
        "remainingQuota": 3,
        "report": {
            "analysis": {
                "meta": { "inspection_node": "木工验收", "image_quality_check": "清晰", "overall_score": 85 },
                "summary": { "status": "FAIL", "conclusion": "主体工艺良好,但吊杆间距存在一处违规。" },
                "checklist_items": [
                    {
                        "item_name": "轻钢龙骨间距",
                        "standard_desc": "间距不大于400mm",
                        "status": "FAIL",
                        "evidence": "照片中可见龙骨间距明显大于400mm。",
                        "rectification": "调整龙骨间距至400mm以内后复检。",
                        "related_media": [ { "type": "image", "url": "https://cdn.thirdparty.com/a.jpg" } ]
                    }
                ]
            },
            "images": [ { "type": "image", "url": "https://cdn.thirdparty.com/a.jpg" } ],
            "analyzedAt": "2026-06-23 14:32:10"
        }
    },
    "message": "",
    "successful": true
}