← [返回主页](../README.md)

# HTTP 接口

---

## 接口一览

| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| GET  | `/` | 无 | 主页（上传入口 + 最近 10 任务进度卡片） |
| GET  | `/health` | 无 | 存活探针 + 设备/模型配置信息 |
| GET  | `/history` | 无 | 历史任务页（分页表格，可按文件名搜索、下载字幕） |
| GET  | `/logs` | 无 | 实时日志页（按级别过滤、自动刷新、可展开 traceback） |
| GET  | `/docs` `/redoc` | Basic Auth | API 文档 |
| POST | `/api/tasks/chunk-uploads` | 无 | 创建分片上传会话 |
| GET  | `/api/tasks/chunk-uploads/{id}/status` | 无 | 查已传分片（断点续传） |
| POST | `/api/tasks/chunk-uploads/{id}/chunks/{index}` | 无 | 上传单个分片（原始二进制 body） |
| POST | `/api/tasks/chunk-uploads/{id}/complete` | 无 | 拼接 + 创建转写任务 |
| GET  | `/api/tasks` | 无 | 任务列表（`limit` / `offset` 分页，`q` 按文件名模糊搜索） |
| GET  | `/api/tasks/{id}` | 无 | 任务状态（status / progress / error） |
| GET  | `/api/tasks/{id}/subtitle?type=bilingual\|en\|zh` | 无 | 下载字幕 |
| GET  | `/api/logs?level=debug\|info\|warning\|error&tail=N` | 无 | 查询日志（按级别过滤，最近 N 条） |
| DELETE | `/api/logs` | 无 | 清空日志缓冲 |

---

## 分片上传协议

1. **建会话** `POST /api/tasks/chunk-uploads`，body 含 `filename` / `size_bytes` /
   `chunk_size` / `total_chunks`，返回 `upload_id`。
2. **查状态** `GET .../status`，返回 `uploaded_chunks`（已传分片下标列表）。
   断点续传时先查此接口，只补传缺失分片。
3. **传分片** `POST .../chunks/{index}`，body 为原始二进制。分片可乱序、可重传覆盖。
4. **完成** `POST .../complete`，服务端按 index 顺序拼接为正式视频文件，创建转写 Task
   并入队。complete 幂等：重复调用返回同一 `task_id`。

---

## 请求/响应示例

创建会话：

```bash
curl -X POST http://127.0.0.1:8000/api/tasks/chunk-uploads \
  -H 'Content-Type: application/json' \
  -d '{"filename":"demo.mp4","size_bytes":10485760,"chunk_size":4194304,"total_chunks":3}'
# → {"upload_id":"a1b2...","filename":"demo.mp4","size_bytes":10485760,"chunk_size":4194304,"total_chunks":3}
```

查任务状态：

```bash
curl http://127.0.0.1:8000/api/tasks/1
# → {"id":1,"filename":"demo.mp4","status":"done","progress":100.0,"error":null,"has_subtitle":true,...}
```

下载字幕：

```bash
curl -OJ http://127.0.0.1:8000/api/tasks/1/subtitle?type=bilingual
```

健康检查（含设备与模型配置）：

```bash
curl -s http://127.0.0.1:8001/health | python -m json.tool
# → {"status":"ok","cuda_available":true,"gpu":"NVIDIA GeForce RTX 3090",
#    "asr_model":"large-v3-turbo","asr_batch_size":32,"asr_beam_size":2,...}
```