# V17人机合一剪辑提效 能力接口标准(CAP-SPEC v3) > 本项目**只定义能力接口的格式标准**,不含任何能力实现。 > **只支持一个聚合网关**:唯一配置项是 `workspace/.env` 的 `TLA_AGG_URL`, > 所有模型能力都从同一个网关按前缀转发;**不再读取单服务地址** > (`TLA_ASR_URL` / `TLA_VL_URL` / `TLA_OCR_URL` / `TLA_FACE_URL` / `TLA_RMBG_URL` / > `TLA_CLIP_URL` / `TLA_DINOV2_URL` / `TLA_MDX_URL` / `TLA_SUBREM_URL` / `TLA_TTS_URL` 均已废弃)。 > 最小要求:**ASR**。推荐完整集:**asr / vl / ocr / 字幕移除(subremove) / tts / 人脸识别(face) / rmbg / clip / dinov2 / mdx(人声分离)**。 > **本项目版本更新会增删和修改接口定义(CAP-SPEC 版本号递增)——agent 自行维护对接更新。** > **部署/启动验收与“没有网关时怎么实现”见 `docs/GATEWAY-SPEC.md`(gateway-spec-v1)**: > 启动 V17 前必须跑 `v17.exe -check-gateway -ws workspace`,通过后才启动 GUI; > 失败先看 `state` 判断“已有但没启动 / 端口防火墙 / 根本没有”,不要连不上就新建; > 确认没有后让用户选择 已有网关 / 本机最小 / 本机完整 / 云 API / 完全不接,确认后才实现。 > 不得把单服务端口填进 `TLA_AGG_URL`。 > 机读版:`GET /api/capabilities`(含网关状态与各能力当前路径);网关清单 `GET /api/gateway`, > 实时验收 `GET /api/gateway/check`。 > 实际网关地址(机器相关)登记在部署机的 `workspace/docs/ENVIRONMENT.md`(R11),不写进本标准。 ## v2 → v3 变更点(2026-11-15) | 变更 | 说明 | |---|---| | 唯一配置项 | 只读 `TLA_AGG_URL`;单服务 `TLA_*_URL` 全部废弃,不再读取 | | 单端口聚合 | 所有能力走同一个网关:`/asr` `/ocr` `/rmbg` `/clip` `/dinov2` `/face` `/mdxsep` `/lfm` | | VL 路径对齐 | 改为 `{gateway}/lfm/v1/chat/completions`,模型名 `lfm` | | ASR 健康 | 改为 `{gateway}/asr/healthz` | | 未提供能力 | 当前聚合网关未提供 `/subremove`、`/tts`;需先在网关加前缀,不允许直连单服务 | ## 网关入口 - 环境变量:`TLA_AGG_URL`,例如 `http://:8080` - 聚合健康:`GET {gateway}/healthz` - 网关换机器只换 IP,端口与路径不变;客户端不得把 `8082/8083/8084/8085/8086` 等直连端口写进配置。 --- ## 通用约定(适用于所有能力接口) - 每个部署暴露 `GET /healthz` → `{"ok":true,...}`(字段可扩展,`ok` 必有); - 请求/响应均为 UTF-8 JSON 或原始字节(Content-Type 标注); - 时间单位一律**秒(浮点)**;图像坐标一律**像素**(相对提交的图像);图像格式 JPEG/PNG 字节; - 错误:HTTP 4xx/5xx + `{"error":"..."}` 或 `{"ok":false,"error":"..."}`; - **局域网部署通常无鉴权**(仅限可信内网使用;如需公网暴露自行加反向代理/鉴权); - **限流**:常见并发上限 4,超限返回 **429 + `Retry-After: 1`**——调用方必须按 `Retry-After` 指数退避重试(1s/2s/4s…),不要丢弃任务; - 部分服务在响应头给出耗时(如 `X-*-Ms` 总耗时 / `X-*-Infer-Ms` 纯推理):排查慢请求先看这两个数, 不需要自己加服务端日志; - agent 在 `workspace/docs/ENVIRONMENT.md` 登记每个能力的地址与状态(R11)。 --- ## 1. ASR 语音索引(最小必需) - 网关前缀:`/asr`(完整 URL:`{gateway}/asr`) - 转写:`POST {gateway}/asr?lang=zh&itn=1`,body = 原始音频字节(任意 ffmpeg 可读格式) → `{"text", "segments":[{"start","end","text"}]}`(秒) - 健康检查:`GET {gateway}/asr/healthz` - 参考实现(CPU):`services/asr/asr_server.py`(sherpa-onnx SenseVoice + Silero VAD) **实测部署的超集字段(TensorRT 服务,向后兼容,缺省即 v1 行为):** | 项 | 说明 | |---|---| | `lang` | `auto/zh/en/yue/ja/ko/nospeech`(v1 只约定 `zh`;`auto` 为推荐默认) | | `srt` | `=1` 时响应追加 `srt` 字段(SRT 字幕全文) | | `punc` | `=1` 标点恢复(默认开) | | 响应 | 追加 `tokens:[{token,start}]`(字级时间戳)与 `stats:{audio_sec,rtf,...}` | | `POST {gateway}/asr/file` | multipart(字段 `file`),查询参数同上 | | `POST {gateway}/v1/audio/transcriptions` | **OpenAI Whisper 客户端兼容**(`response_format=json|text|srt|verbose_json`);网关前缀 `/v1/audio` | - 用途:台词/语音检索标记、字幕轨、语音节奏分析 - 对接状态:本项目后端只消费 `POST /asr` 主契约(`internal/asr`);其余字段供 agent 直接取用 ## 2. VL 视觉理解(画面描述 / 问答) - 网关前缀:`/lfm`(完整 URL:`{gateway}/lfm/v1/chat/completions`) - 形态:**OpenAI Chat Completions 兼容**(与主流视觉模型同构) - 调用:`POST {gateway}/lfm/v1/chat/completions` ```json { "model": "lfm", "messages": [{"role": "user", "content": [ {"type": "text", "text": "用中文描述这张画面:主体、动作、场景。"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,xxxx"}} ]}], "temperature": 0.1, "max_tokens": 300, "chat_template_kwargs": {"enable_thinking": false} } ``` → OpenAI 响应,取 `choices[0].message.content`。 - 图片以 **base64 data URL** 放进 `content` 数组,与文字并列;视频**逐帧抽图**发送(ffmpeg 抽帧),不整段直传; - **先缩图再发**:最长边 ≤512px(越快越省 token); - 网关 `/lfm` 已关闭“思考”(服务端 `-rea off`),通常直接返回 `content`;如自建同形态网关仍要带 `chat_template_kwargs.enable_thinking=false`, 否则模型只输出 reasoning、`content` 为空(实测头号坑); - 局域网本地部署无需 `Authorization`,不传 `detail` 字段; - 健康检查:`GET {gateway}/lfm/health`。 - 用途:画面理解、场景描述、内容问答、给 agent 的"眼睛"(看帧说话) > **分工红线:要"理解画面"用 vl;要"逐字精确取字"用 ocr。** > 生成式 VL 在密集中文正文上会系统性漏字/形近误读/数字串错(实测结论),不要用它做取证。 ## 3. OCR 文字识别 - 网关前缀:`/ocr`(完整 URL:`{gateway}/ocr`) - 识别:`POST {gateway}/ocr`,body = 图像字节(JPEG/PNG) → `{"results":[{"box":[x,y,w,h],"text","conf"}]}`(box 为提交图像的像素坐标) - 用途:画面内嵌字幕/标定位(配合字幕移除与素材合规检查)、错误码/版本号/文件名等**逐字精确**取证 > 当前无局域网 HTTP 部署。备选形态(对接时包一层 HTTP 即符合本契约): > 本机 Python 库(rapidocr-onnxruntime,确定性、字符级零误差)或云端 MaaS OCR(OpenAI chat/completions 形态, > 精度高但需 API Key——Key 属私有凭据,只放 workspace/.env 或 agent 私有配置,**不入仓库、不入文档**)。 ## 4. 字幕移除(inpaint) - 网关前缀:`/subremove`(当前网关未提供;需先在网关加前缀) - 逐帧:`POST {gateway}/subremove`,body = 图像字节 → 清理后图像字节(PNG/JPEG,同尺寸) - 契约为逐帧(agent 用 ffmpeg 抽帧→逐帧→回封);视频直传不做(带宽/延迟) - 用途:擦原字幕、擦台标水印 ## 5. TTS 语音合成 - 网关前缀:`/tts`(当前网关未提供;需先在网关加前缀) - 合成:`POST {gateway}/tts`,JSON `{"text","voice"?,"speed"?}` → 音频字节(wav/mp3)+ 响应头 `X-Duration-Sec` - 用途:解说/配音轨生成(配合 clip.add audio 轨) ## 6. 人脸识别 - 网关前缀:`/face`(完整 URL:`{gateway}/face/detect`) - 检测:`POST {gateway}/face/detect`,body = 图像字节(multipart `file` 亦可) → `{"faces":[{"score","box":[x1,y1,x2,y2](原图坐标),"kps":[[x,y]×5 左眼/右眼/鼻尖/左嘴角/右嘴角]}]}` - 特征:`POST {gateway}/face/embed`,body = 图像字节 → `{"faces":[{"score","box","vec":[512 floats 已 L2 归一化]}]}`(ArcFace 口径;多脸按分数降序,比对通常取 `faces[0]`) - 比对:`POST {gateway}/face/compare`,JSON `{"a":[...],"b":[...]}`(两组 embedding) 或 multipart 两张图 → `{"similarity":0.87,"same_person":false}`(`same_person` 阈值 0.35,可只取 similarity 自行判定) - 用途:人脸选区(`selection.create kind=face`)→ 跨集找人;embedding 写入 `Selection.Vector`(本项目预留字段) - 小脸/侧脸检测不到时:先裁剪放大再送 ## 7. RMBG 背景移除 - 网关前缀:`/rmbg`(完整 URL:`{gateway}/rmbg`) - 抠图:`POST {gateway}/rmbg`,body = 图像**原始字节**(`Content-Type: application/octet-stream`—— 用 form-urlencoded 会被 8KB 表单上限拦成 413) - 查询参数: | 参数 | 取值 | 默认 | 说明 | |---|---|---|---| | `mode` | `rgba` \| `alpha` \| `rgb` | `rgba` | 透明底 PNG / 灰度蒙版(最小最快)/ 合成底色 | | `bg` | 6 位 hex | `FFFFFF` | 仅 `mode=rgb`(绿幕 `00FF88` 等) | | `format` | `png` \| `json` \| `jpg` | `png` | `json` 返回 base64 | | `q` | 1–100 | 92 | 仅 jpg | → 图片字节(与原图同宽高,不裁剪不缩放); - 响应头 `X-*-Ms`(总耗时)/`X-*-Infer-Ms`(纯推理);413=超上传上限、429=并发超限(退避重试) - 用途:封面/贴片合成、背景替换;只要蒙版做二次合成时用 `mode=alpha`(体积约 1/30、快近半) ## 8. CLIP 图文对齐 - 网关前缀:`/clip`(完整 URL:`{gateway}/clip/image`) - 图嵌入:`POST {gateway}/clip/image`(multipart `file`,或 JSON `{"image_base64":"..."}`) → `{"dim":512,"vec":[...]}`(**已 L2 归一化**,余弦相似度可直接点积) - 文嵌入:`POST {gateway}/clip/text`,JSON `{"texts":["..."]}`(单次 ≤64 条) → `{"results":[{"text","vec":[...]}]}` - 图文相似度(可选):`POST {gateway}/clip/similarity`(图 + texts)→ `{"results":[{"text","score"}]}` - 相似度由调用方计算(余弦);用途:语义检索镜头("找出吃饭的镜头"类需求) - 注意:向量跨模型版本不可混用(预处理口径变了必须重算) ## 9. DINOv2 视觉特征 - 网关前缀:`/dinov2`(完整 URL:`{gateway}/dinov2/image`) - 嵌入:`POST {gateway}/dinov2/image`(multipart `file`,或 JSON `{"image_base64":"..."}`) → `{"dim":384,"vec":[...]}`(**未归一化**——自行 L2 归一化后再算余弦) - 用途:视觉相似镜头聚类/去重(配合场景检测) ## 10. MDX 人声分离(vocals separation) - 网关前缀:`/mdxsep`(完整 URL:`{gateway}/mdxsep`) - 分离:`POST {gateway}/mdxsep?mode=vocals` → `audio/wav`(44.1kHz 立体声 PCM16 人声轨); `?mode=instr` → 伴奏轨;不带 `mode` → JSON `{"vocals_wav_base64","instrumental_wav_base64",...}` (大文件建议直接取二进制,JSON 体积约为 WAV 的 2.7 倍) - 输入支持 WAV 及其它格式(mp3/m4a/视频等,服务端内部 ffmpeg 转码);非 44.1kHz 自动重采样 - 用途:配音/解说前的伴奏剥离、BGM 提取、音频轨精修(配合 tts 与 clip.add audio 轨) --- ## 能力缺失时的行为 | 能力缺失 | 影响 | |---|---| | ASR | 语音检索/字幕轨不可用;其余(导入/时间线/标记/渲染)正常 | | VL | agent"看帧说话"不可用;OCR(若部署)仍可取字 | | MDX | 人声/伴奏分离不可用;其余音频能力正常 | | 其他任意能力 | 对应 agent 能力不可用;核心剪辑流程不受影响 | agent 接入新能力后必须:更新 `workspace/docs/ENVIRONMENT.md`(R11)并在能力表中登记状态。