audio2text/docs/API.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。

---

请求/响应示例

创建会话：

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}

查任务状态：

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,...}

下载字幕：

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

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

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,...}