# API 契约：视频处理

---

## POST /api/video/process

**权限**: ADMIN  
**描述**: 为已上传的视频资料创建异步处理任务

**请求体**:
```json
{
  "sourceId": 50,
  "jobType": "FRAME_EXTRACT",
  "params": {
    "frameInterval": 30,
    "mode": "FRAME"
  }
}
```

jobType 可选值：`FRAME_EXTRACT`（帧提取）、`VIDEO_TO_TEXT`（片段转文字）

**响应** `201`:
```json
{
  "code": "SUCCESS",
  "data": {
    "jobId": 200,
    "sourceId": 50,
    "jobType": "FRAME_EXTRACT",
    "status": "PENDING"
  }
}
```

---

## GET /api/video/jobs/{jobId}

**权限**: ADMIN  
**描述**: 查询视频处理任务状态

**响应** `200`:
```json
{
  "code": "SUCCESS",
  "data": {
    "id": 200,
    "status": "RUNNING",
    "processedUnits": 15,
    "totalUnits": 50,
    "retryCount": 0,
    "errorMessage": null,
    "startedAt": "2026-04-09T10:05:00"
  }
}
```

---

## POST /api/video/jobs/{jobId}/reset

**权限**: ADMIN  
**描述**: 手动重置 FAILED 状态的任务为 PENDING，允许重新触发（FAILED → PENDING 不在自动状态机中）

**响应** `200`: `{"code": "SUCCESS", "data": null}`  
**失败**: `409` `INVALID_STATE`: 任务状态不为 FAILED

---

## POST /api/video/callback（内部接口）

**权限**: AI 服务内部调用（IP 白名单 / 服务密钥）  
**描述**: AI 服务回调，通知视频处理结果（幂等：重复成功回调静默忽略）

**请求体**:
```json
{
  "jobId": 200,
  "success": true,
  "outputPath": "frames/50/",
  "errorMessage": null
}
```

**响应** `200`: `{"code": "SUCCESS", "data": null}`