VDE 响应与事件契约

更新时间：2026年09月08日 13时20分03秒（UTC+8）

本次仅迁移文档，不改变接口行为。原有“候选”标识保留，表示发布状态尚需逐项核验，不代表本次已上线该能力。

JSON envelope

VDE /api/v1/* 使用统一结构：

{
  "code": 0,
  "data": {},
  "msg": "ok"
}

• 成功响应使用 code: 0。
• 错误响应使用稳定的机器可读字符串 code，data 为 null，HTTP status 表示传输层结果。
• 请求校验错误返回 HTTP 422 和 invalid_request；不得把框架默认错误页或堆栈返回给调用方。
• 每个 HTTP 响应带 X-Request-ID；调用方可传入最长 128 个可打印字符的 X-Request-ID，否则服务生成新 ID。

服务鉴权

除 /healthz 外，VDE /api/v1/* 要求：

Authorization: Bearer <SERVICE_TOKEN>

未配置服务 token 时 fail closed，返回 HTTP 503 / service_auth_not_configured；凭证缺失或错误时返回 HTTP 401 / service_unauthorized，并附带 WWW-Authenticate: Bearer。浏览器只访问受会话保护的 /api/video-dataset/* BFF，由 BFF 在服务器侧注入 token，且不向 VDE 转发浏览器 Cookie 或 Authorization。

Job SSE

GET /api/v1/jobs/{job_id}/events 返回 text/event-stream：

• event: job：data 仍使用标准 envelope，data 为当前 Job。
• event: error：数据库或目标不可用时返回机器可读错误 envelope，然后关闭连接。
• event: timeout：单次流达到上限；客户端应先 GET 当前状态，再使用最新 event ID 重连。
• 注释心跳 : heartbeat 每 15 秒发送一次，不改变 Job 状态。
• id 是状态游标；重连时通过 Last-Event-ID 继续，服务不会重复发送相同快照。
• GET /api/v1/assets/{asset_id}/jobs 返回该素材最近的 durable jobs，页面重挂载后据此恢复非终态订阅。
• succeeded、failed、dead、cancelled 为终态，发送终态快照后关闭流。

响应同时设置 Cache-Control: no-cache 与 X-Accel-Buffering: no，代理不得缓冲事件流。