4054a1133b
Phase 0：research.md（10项技术决策，无需澄清项） Phase 1：data-model.md（11张表+Redis结构），contracts/（8个模块API契约），quickstart.md（Docker Compose启动+流水线验证） plan.md：宪章11条全部通过，项目结构确认
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}`
|