视频识别

POST/v1/vision/tasks

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

视频识别采用长任务模型：请求方提交直播流地址（创建时先做协议与安全校验、再做连通性探测，探测失败不产生任务也不扣减额度）或直接上传视频文件创建任务后，平台持续推理，按次计额度（5 次/日）。任务结果保留 90 天，逾期自动删除。当前开放人车（person_vehicle）、船舶（ship）、钓鱼行为（fishing）、火焰烟雾（fire_smoke）与牛羊（cow_sheep）五个场景；任意未知 JSON 字段都会被拒绝。

创建任务

POST/v1/vision/tasks

参数名	位置	类型	必填	说明
Authorization	header	string	是	试用密钥，格式 `Bearer <API Key>`。
Idempotency-Key	header	string	是	标准 UUID 形态的幂等键。同键同语义重放返回 200 与原任务；同键但请求语义不同返回 `OP-TASK-REQUEST-INVALID`。
scene_code	body	enum	是	识别场景。可用值以 `GET /api/op/v1/scenes` 返回的 enabled 场景为准。
stream_url	body	string	是	用户有权访问的直播流地址，仅支持 `http` / `https` / `rtsp` / `rtmp`，可携带 URL 用户信息，需可从服务端访问；平台不提供隐式样例流。创建时先做协议与安全校验、再做连通性探测；缺失、空值或校验失败返回 `OP-TASK-REQUEST-INVALID`（`details.reason` 为 `stream_url_invalid` 或 `stream_unreachable`），不产生任务也不扣减额度。

curl --request POST '/v1/vision/tasks' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: b2074044-213b-4766-bcd9-8f7639bdae04' \
  --header 'Content-Type: application/json' \
  --data '{"scene_code":"fire_smoke","stream_url":"rtsp://media.example.com/live/drone01"}'

响应状态

201首次创建成功，返回任务。

200同键同语义重放，返回原任务，不重复扣额。

202提交结果未知（status=resolving）。这不是错误：推理服务可能已受理，不得据此重发新键，轮询任务状态即可。

{
  "task_id": "a2074044-213b-4766-bcd9-8f7639bdae04",
  "request_id": "b2074044-213b-4766-bcd9-8f7639bdae04",
  "scene_code": "fire_smoke",
  "status": "running",
  "result_expires_at": "2026-11-01T10:00:00Z",
  "created_at": "2026-08-03T10:00:00Z",
  "updated_at": "2026-08-03T10:00:10Z"
}

视频文件上传

POST/v1/vision/video-tasks

除直播流地址外，也可以直接上传视频文件创建识别任务。请求为 multipart/form-data，文件由平台中转至对象存储后提交推理；创建响应、幂等重放、状态机、播放与任务历史同 POST /v1/vision/tasks 完全一致，同样按次计额度。

参数名	位置	类型	必填	说明
Authorization	header	string	是	试用密钥，格式 `Bearer <API Key>`。
Idempotency-Key	header	string	是	标准 UUID 形态的幂等键，语义与创建任务一致。
scene_code	form	enum	是	识别场景，取值同创建任务的 `scene_code`。
file	form	file	是	视频文件，仅支持 MP4 / MOV，单文件不超过 512MB。

curl --request POST '/v1/vision/video-tasks' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Idempotency-Key: b2074044-213b-4766-bcd9-8f7639bdae04' \
  --form 'scene_code=person_vehicle' \
  --form 'file=@/path/to/drone_scene.mp4'

视频文件任务的结果帧时间为视频内时间（PTS）毫秒偏移，与直播流任务的 Unix 毫秒时间戳不同；播放进度与时间轴对齐请以 PTS 为准。

查询任务状态

GET/v1/vision/tasks/{task_id}

返回字段与创建响应一致。任务按密钥隔离：跨主体读写统一返回 404。

拉取结果帧

GET/v1/vision/tasks/{task_id}/results

参数名	位置	类型	必填	说明
cursor	query	string	否	不透明分页标记；`next_cursor` 为空表示已到底。
limit	query	int	否	每页帧数，1–500，缺省由服务端取默认值。
min_score	query	float	否	置信度下界，0–1。未传时使用任务创建时冻结的业务阈值（默认 0.80）；低于该任务推理写入下界时按下界钳制返回（低于下界本无留存数据，返回集相同），不报错。

阈值是读时过滤，不重跑推理：检出按推理下界全量入库（两套置信度——低置信的模棱两可数据留存作采集样本，不按展示值过滤），调高或调低 min_score 都直接从已存帧里筛选，零额外推理开销。低于推理下界的检出根本不在库里，拖得更低也不会变多。

{
  "items": [
    {
      "frame_id": "f_01J8Z…",
      "frame_time_ms": 1722686212340,
      "image": { "width": 1920, "height": 1080 },
      "objects": [
        {
          "label": "fire",
          "score": 0.92,
          "bbox": { "format": "xyxy_pixel", "x1": 812, "y1": 364, "x2": 940, "y2": 460, "width": 128, "height": 96 },
          "track_id": "trk_17"
        }
      ],
      "objects_total": 3
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjEwMH0"
}

字段说明

frame_time_msint64帧时间（毫秒）。直播流任务为 Unix 毫秒时间戳；视频文件任务为视频内 PTS 毫秒偏移。

objects[]array帧内检出目标：label 类别、score 置信度、bbox 位置框（恒为左上/右下像素坐标 xyxy_pixel）、track_id 跨帧跟踪号。

objects_totalint过滤前的检出总数，仅在请求带了 min_score 时出现——「共检出 M 条，符合阈值 N 条」靠它区分。

停止任务

POST/v1/vision/tasks/{task_id}/stop

对运行中的任务发起持久停止，返回任务的最终状态。已结束的任务返回 OP-TASK-NOT-STOPPABLE。

状态语义

状态	含义
submitting	已受理（额度已计），正在向推理服务提交。
resolving	提交确认中：提交结果未知，平台正在确认受理结果。不是失败，不会重复扣减额度。
running	运行中，结果帧持续产出。
stopping	停止中：停止指令已发出，等待推理服务确认。
stopped	已停止（终态）。
succeeded	已完成（终态）。
failed	失败（终态）。
refunded	提交被拒或确认未创建（终态），额度已按原消费日退还。

任务状态以平台查询为准持续推进；提交超时的任务会转入人工核实流程，核实前仍占用额度与并发，核实后自动退款或继续运行。

完整错误码表见错误码，任务生命周期相关错误在 TASK 族。