88 lines
1.6 KiB
Markdown
88 lines
1.6 KiB
Markdown
|
# 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}`
|