图片识别

POST/v1/vision/image-detections

认证方式：所有请求需在请求头中携带试用密钥（API Key），详情请查看认证。

图片识别采用同步批量模型：一次请求上传 1..10 张图片，同步返回逐张检测结果。额度按【实际成功张数】结算（100 张/日），识别失败的张数不计额度。每次调用都会落任务记录，结果与上传图片保留 90 天，到期自动删除。当前正式支持人车（person_vehicle）、船舶（ship）、钓鱼行为（fishing）、火焰烟雾（fire_smoke）与牛羊（cow_sheep）五个模型；具体目标词表以场景列表返回值为准。

创建图片检测

POST/v1/vision/image-detections

参数名	位置	类型	必填	说明
Authorization	header	string	是	试用密钥，格式 `Bearer <API Key>`。
Idempotency-Key	header	string	是	标准 UUID 形态的幂等键。同键重试按重放恢复原始逐张结果，不重复扣减额度。
files	body	file[]	是	multipart 文件字段，文件字段仅接受 `files` 一个字段名。图片类型 JPG / PNG / WEBP，单张不超过 8 MiB，总请求体不超过 81 MiB，批量 1..10 张。
scene_code	body	string	否	推理场景（识别类型），取场景列表里已开放的 `code`（如 `fire_smoke`、`cow_sheep`），目标词表与推理下界随场景；缺省按 `fire_smoke`。场景计入幂等指纹：同一幂等键换场景视为不同请求。

curl --request POST '/v1/vision/image-detections' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: b2074044-213b-4766-bcd9-8f7639bdae04' \
  --form 'scene_code=fire_smoke' \
  --form 'files=@drone_scene_0730.jpg' \
  --form 'files=@drone_scene_0731.jpg'

响应

首次请求返回 201；同一 Idempotency-Key 重放返回 200 且带 "replayed": true。results 逐张给出 status（succeeded / failed）：部分成功是常态，失败张带 error_code 且不计额度。bbox 为原图像素坐标（xyxy_pixel），可直接用于叠框渲染。

{
  "task_id": "a2074044-213b-4766-bcd9-8f7639bdae04",
  "request_id": "b2074044-213b-4766-bcd9-8f7639bdae04",
  "status": "succeeded",
  "results": [
    {
      "seq": 0,
      "status": "succeeded",
      "objects": [
        {
          "label": "fire",
          "score": 0.91,
          "bbox": { "format": "xyxy_pixel", "x1": 896, "y1": 378, "x2": 1152, "y2": 594, "width": 256, "height": 216 }
        }
      ]
    },
    { "seq": 1, "status": "failed", "error_code": "OP-TASK-UPSTREAM-DOWN" }
  ]
}

实现边界

输入开放 API 收 multipart 图片字节，由后端代传对象存储；不要求开发者先准备对象 key。

结算按实际成功张数结算；图片中转失败与推理失败的张数均不消耗额度。

幂等同步接口的客户端超时重发是常态——重试必须沿用同一 Idempotency-Key，否则按新请求重复计费。

限流入口按主体限制并发与 QPS，触发返回 OP-QUOTA-RATE-LIMITED，可稍后重试。

错误码

错误码	HTTP 状态	说明
OP-AUTH-REQUIRED	401	缺少或无效的试用密钥
OP-TASK-REQUEST-INVALID	400	参数错误：缺 Idempotency-Key 或形态非 UUID、字段名越界（文件字段仅 `files`、值字段仅 `scene_code`）、张数越界、类型或大小超限
OP-TASK-SCENE-UNAVAILABLE	400	`scene_code` 不存在或未开放
OP-QUOTA-DAILY-EXHAUSTED	429	今日图片额度已用完，明日 00:00（UTC+8）重置
OP-QUOTA-RATE-LIMITED	429	超出并发或 QPS 限制，可稍后重试
OP-TASK-UPSTREAM-DOWN	503	推理服务暂时不可用；出现在逐张 error_code 时仅该张失败且不计额度
OP-TASK-BREAKER-OPEN	503	服务维护中，暂停受理新任务
OP-SYS-UNAVAILABLE	503	能力依赖未装配（对象存储或推理底座不可达）

完整错误码表见错误码。