Skip to content

API_GUIDE.md

Latest commit

 

History

History
194 lines (151 loc) · 12.3 KB

API_GUIDE.md

File metadata and controls

194 lines (151 loc) · 12.3 KB
Raw

LetsGoVideoAgent API 中文说明

对应仓库 OpenAPI 快照：2026-08-13，共 37 条路由。
本文解释接口“用来做什么”；字段的最终约束以运行中的 OpenAPI 为准。

1. 查看与更新接口文档

启动后端后可直接查看：

  • Swagger（适合直接试接口）：http://127.0.0.1:8000/docs
  • ReDoc（适合连续阅读）：http://127.0.0.1:8000/redoc
  • OpenAPI JSON：http://127.0.0.1:8000/openapi.json
  • API 前缀：http://127.0.0.1:8000/api/v1

仓库中的静态快照为 docs/api/openapi.json。路由或 Pydantic Schema 改动后执行：

backend\.venv\Scripts\python.exe scripts\export-openapi.py

2. 通用约定

  • JSON 请求使用 Content-Type: application/json，上传接口使用 multipart/form-data。
  • 视频、项目、Skill、Run 和 Trace 的标识通常是 UUID。
  • 时间统一使用整数毫秒；例如 297000 表示 04:57.000，不要传浮点数。
  • 视频处理是异步任务：启动接口返回后，应轮询处理状态和 Agent Trace，而不是让 HTTP 请求一直等待。
  • 业务错误使用 application/problem+json；422 通常表示请求字段或类型不合法。
  • 当前是本地个人版，尚未提供完整登录/RBAC；暴露到公网前必须增加鉴权、限流和上传安全策略。

3. 健康检查

方法与路径 用途
GET /health/live 判断 FastAPI 进程是否存活。只回答“进程活着”，不保证外部依赖可用。
GET /health/ready 检查后端是否已准备接收业务请求，并返回关键依赖状态。启动脚本应优先使用它。

4. 视频接入与处理

方法与路径 用途 关键输入/输出
GET /videos 获取视频库，用于左侧列表和恢复上次任务。 返回视频列表及处理状态。
GET /videos/{video_id} 获取单个视频元数据。 video_id；返回标题、时长、来源和状态。
POST /videos/uploads 上传本地视频。 表单字段 file，支持 MP4/MOV/MKV/WebM。
POST /videos/imports 登记并异步下载网页视频。 url、可选 title、rights_confirmed。
POST /videos/{video_id}/processing 启动或重试视频理解流水线。 返回 Processing Run/Trace 标识；重复调用应遵循幂等和重试规则。
GET /videos/{video_id}/processing 查询处理阶段、百分比、预计剩余时间和错误。 前端进度面板轮询此接口。
GET /videos/{video_id}/timeline 获取字幕、画面、OCR、章节、代表帧等多轨时间轴。 返回 TimelineArtifact 集合。
GET /videos/{video_id}/semantic-events 获取便于 Agent 检索的语义事件。 包含时间范围、类型、文本和来源。
GET /videos/{video_id}/narrative-context 获取全片总览、层级章节和快捷理解内容。 主界面的“快速了解视频”使用。

网页导入示例：

{
  "url": "https://www.bilibili.com/video/BVxxxxxxxxx/",
  "rights_confirmed": true
}

推荐调用顺序：

上传或网页导入
  → 取得 video_id
  → POST /processing
  → 轮询 GET /processing
  → 完成后读取 narrative-context、timeline 和 semantic-events

5. 视频问答

POST /videos/{video_id}/questions

对全片、片段、某一刻或精确帧提问。关键字段：

  • query：问题，1–2000 字符；
  • target：问题作用范围；省略时按全片理解；
  • use_web_search：为 true 时必须执行联网研究，并把网页来源与视频证据分开；
  • conversation_id：继续同一段对话；
  • trace_id：需要把前端已建立的 Trace 贯穿本次请求时使用。

四种目标：

{"kind": "global"}
{
  "kind": "range",
  "time_range": {"start_ms": 120000, "end_ms": 180000}
}
{"kind": "moment", "timestamp_ms": 297000, "context_window_ms": 8000}
{"kind": "frame", "timestamp_ms": 297000}

moment 会结合前后文，frame 会重新抽取指定时刻的真实画面并优先交给 VLM。响应包含答案、模型使用、视频/图片/网页证据以及 Run/Trace 信息。

6. Agent、Trace、成本与系统观测

方法与路径 用途
GET /agent-runs/{run_id} 查看一次处理或问答 Run 的整体状态、预算和各 Agent 步骤。
GET /agent-runs/{run_id}/trace 获取该 Run 的公开 Trace 事件，供运行观测界面增量展示。
GET /traces/{trace_id} 按 Trace ID 查询跨节点事件。
GET /costs/summary 汇总人民币成本，可按模型、Agent、视频和用途理解花费。
GET /observability/usage 获取较细的模型 UsageEvent，定位某次 Token 与费用。
GET /observability/system 获取 Agent 注册表、Harness 策略、模型路由、MCP 和运行组件状态。

Trace 是公开执行摘要，不包含隐藏思维链、密钥、完整系统 Prompt 或原始视频内容。

7. 垂类 Skill 项目

方法与路径 用途 关键输入
GET /skill-projects 获取全部垂类项目。 无。
POST /skill-projects 创建“Zc 故事”等长期样本项目。 name、goal、可选 description。
GET /skill-projects/{project_id} 获取项目、样本流水线、Agent 分配、成本和视频洞察。 项目 UUID。
DELETE /skill-projects/{project_id} 删除项目关系。 属于破坏性操作；前端必须二次确认。
POST /skill-projects/{project_id}/videos 一次加入 1–50 个网页视频样本并处理。 urls、rights_confirmed。
POST /skill-projects/{project_id}/items/{item_id}/retry 重试某个失败样本，不重跑整个项目。 项目与样本 ID。
POST /skill-projects/{project_id}/skill 把现有 Skill 关联到项目。 skill_id。

项目用于组织同类视频，不等于 Skill。样本处理完成后，用户再选择其中 1–8 条生成独立草案。

8. Skill 草案、版本和绑定

方法与路径 用途 关键输入
GET /skills 获取全部 Skill 及稳定编号。 无。
POST /skills/generate 从已选样本创建一个全新的 Skill v1 草案。 video_ids、goal、可选 display_name。
GET /skills/{skill_id} 查看内容、全部版本、验证结果和绑定。 Skill UUID。
POST /skills/{skill_id}/regenerate 用一组新样本为同一个 Skill 生成新版本。 video_ids、可选 goal；这是低层版本接口，不等于创建独立 Skill。
POST /skills/{skill_id}/refine 根据自然语言继续修改当前 Skill，生成 v2/v3。 instruction、可选 base_version。
POST /skills/{skill_id}/versions/{version}/publish 人工发布指定版本，并生成运行时 Skill 产物。 Skill UUID 和版本号。
POST /skills/{skill_id}/rollback 将当前发布版本回滚到指定历史版本。 version。
POST /skills/{skill_id}/bindings 把已发布 Skill 绑定到 1–100 个视频。 video_ids。
DELETE /skills/{skill_id} 删除一个 Skill、版本、绑定和项目引用。 破坏性操作，必须二次确认。
POST /skills/batch-delete 批量删除 1–100 个 Skill。 skill_ids。
GET /videos/{video_id}/skill 查看视频当前实际绑定的 Skill 与版本。 视频 UUID。
DELETE /videos/{video_id}/skill 解绑视频 Skill，恢复通用理解。 视频 UUID。

最容易混淆的三个动作：

generate   = 新建一个独立 Skill，从 v1 开始
refine     = 按用户意见修改同一个 Skill，形成 v2/v3
regenerate = 给同一个 Skill 换样本重新归纳，形成新版本

9. v1.1 Script Studio

方法与路径 用途 关键输入
GET /script-projects 获取脚本项目列表。 无。
POST /script-title-suggestions 提纲生成后，同时返回 Skill 原样本视频标题与按其系列前缀、分隔符、标点和长度生成的建议。 skill_id、idea、可选 skill_version / project_id。响应中的 references 是原视频标题，items 是结合当前提纲生成的新建议；失败不阻止项目/提纲创建。
POST /script-projects 锁定一个已发布 Skill 版本并创建脚本项目。 内部项目名 title、idea、skill_id、可选 video_title / skill_version、brief。未传视频标题时暂用项目名占位。
GET /script-projects/{project_id} 获取脚本、全部版本、A13–A15 状态与最近 Trace。 脚本项目 UUID。
PATCH /script-projects/{project_id} 独立保存用户从提纲页选择或自定义的视频标题，不覆盖内部项目名。 video_title。
DELETE /script-projects/{project_id} 删除脚本项目及其全部草案版本。 破坏性操作，前端必须二次确认。
POST /script-projects/{project_id}/outline A13 根据创意、预设和 Skill 生成独立提纲。 项目 UUID。
PATCH /script-projects/{project_id}/outline 保存逐段正文、逐段批注与整体改进建议。 outline、overall_note。
POST /script-projects/{project_id}/outline/revise 先保存编辑，再让 A13 按逐段批注和整体建议真正重写提纲。 可选 instruction；仅使用已保存批注时可传空对象，返回更新后的完整工作区。
POST /script-projects/{project_id}/drafts A14 生成角色对白、分镜、景别和运镜，A15 随后评估；再次调用形成新脚本版本。 可选 instruction。
PATCH /script-projects/{project_id}/drafts/{version} 直接保存当前成稿的口播、分镜、景别和运镜修改，并重新执行确定性评估。 blocks。
DELETE /script-projects/{project_id}/drafts/{version} 只删除一个提纲或一个脚本版本，保留项目和其他版本。 项目 UUID 与内部产物版本号。
GET /script-projects/{project_id}/drafts/{version}/export 导出版本化脚本。 format=markdown 或 json。

创建时只接受已发布 Skill。brief.max_tokens 与 max_cost_usd 会和系统硬上限取交集，前端传入更大值不会扩大权限或预算。提纲与全文分两次调用：提纲在 UI 中不占脚本版本号，确认后才生成“脚本 1”。手工保存的提纲总时长必须严格等于项目目标时长；仍有未应用批注时不能直接生成成稿。A13/A14 会读取 Skill 的 title_patterns、recurring_characters 与 character_relationships，把“朋友”等泛称落到已知人物。逐段批注和整体建议先由 A13 修订提纲，不得原样进入对白。完整脚本按 outline_section_index 将每个章节拆成多个镜头块，保存自然的 角色名：台词、画面、景别、运镜、屏幕文字、时间和 creative/sourced/verify 标记，不写回 SkillContent。A14 输出在持久化和展示前都执行对白格式/元指令过滤；读取旧稿时若识别到历史遗留的风格说明或剧本描述，会自动生成合规对白替换。A15 会结合对白字数与语速检查内容密度，并检查镜头排序、重叠、空档和越界；严重欠时长或过密属于硬错误，不能被其他分项平均成“通过”。

10. 常见错误

状态/现象 常见原因 处理
422 毫秒传了浮点数、UUID 错误、字段超长 对时间戳取整，并查看 Swagger 的 Schema。
404 Not Found 前端仍调用旧路径，或资源 ID 已删除 对照本文件与 openapi.json，检查浏览器 Network。
Failed to fetch 8000 端口未就绪、代理/CORS、后端异常退出 先检查 /health/live 与后端错误日志。
处理接口返回但没结果 任务是异步的 轮询 /processing 并查看对应 Agent Run/Trace。
勾选联网但没有来源 MCP/SearXNG 不可用或调用未执行 查看 /observability/system 的 MCP 状态和 Trace。

11. 修改接口时的维护清单

  1. 修改路由和 Pydantic 请求/响应模型；
  2. 增加正常、校验失败、资源不存在和外部依赖失败测试；
  3. 重新导出 docs/api/openapi.json；
  4. 更新本文相应接口的用途和示例；
  5. 若为破坏性变更，升级 /api/vN 或保留兼容期；
  6. 前端类型、错误展示和 Agent Trace 同步更新。