智能口播剪辑

对口播毛片做一键智能剪辑，输出达到人工粗剪水准的结果：

去错读重读：同一段内容多次录读时，只保留最后一次读顺的版本；错读、口误、半句弃读全部剔除（支持句内级别的精细切分）；
气口清理：句内过长的停顿与吸气声自动收紧；
节奏整形：按文稿标点控制停顿时长（逗号 / 句号 / 问号 / 段落各自可调），切点自动吸附到音频能量最低处，避免硬切爆音。

支持两种模式：提供文稿（script）时以文稿为基准对齐，剪辑质量最佳；不提供时由智能分析自动重建终稿。

产物分三档（outputs 自由组合）：剪辑时间线 + 剪辑报告（必出）、剪辑工程文件（剪映 / CapCut / Premiere / FCPX / OTIO，可在剪辑软件中继续精修）、渲染成片（mp4）。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/video_oral_cut`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）
计费	按输入视频时长（分钟）计费

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	口播毛片视频的文件 ID（先经文件上传获取）
`script`	`string`	否	—	文稿原文（含标点与换行，去空白后 10 ~ 50000 字）。强烈建议提供：有稿模式按文稿逐字对齐，质量最佳；缺省时走智能重建终稿
`la`	`string`	否	`zh-CN`	语种。当前主推中文，其余语种尽力而为
`outputs`	`array`	否	`["timeline"]`	产物选择，取值 `timeline` / `project` / `video` 任意组合。`timeline`（时间线+报告）恒为必出
`project_formats`	`array`	否	全部 8 种	`outputs` 含 `project` 时生效，取值同工程文件生成的 `output_formats`
`render`	`object`	否	`{}`	`outputs` 含 `video` 时生效，字段见下表
`rhythm_preset`	`string`	否	—	节奏预设：`steady`（稳健）/ `concise`（精练）/ `compact`（紧凑），见下方预设表。缺省 = 内置默认节奏。预设铺底后，下方各节奏散参数仍可逐项覆盖微调
`adaptive_rhythm`	`boolean`	否	`true`	自适应节奏：自动学习说话人自身的停顿习惯（顿号停多久、句号停多久），以本人节奏为基准整形停顿并清理句中犹豫停顿——成片更像本人说话。`false` 退回固定参数表模式
`punctuation_breaks`	`object`	否	见下表	标点 → 停顿秒数映射，传入项覆盖默认值/预设值（每项 0 ~ 5 秒）
`intra_gap_max`	`number`	否	`0.35`	句内停顿超过此秒数视为气口，触发收紧（0 ~ 5）
`intra_gap_target`	`number`	否	`0.10`	气口收紧到的目标秒数，必须小于 `intra_gap_max`
`pad_in`	`number`	否	`0.05`	每个保留片段头部的呼吸余量（秒，0 ~ 5）
`pad_out`	`number`	否	`0.08`	每个保留片段尾部的呼吸余量（秒，0 ~ 5）
`visual_assist`	`boolean`	否	`false`	视觉辅助找补：用画面说话检测交叉验证语音识别，防止偶发漏识别的段落被误剪，并尝试找回漏识别的文字。会增加处理耗时（与主识别并行执行），不额外计费
`source_path`	`string`	⚠️ 条件必填	—	毛片在你剪辑环境中的本地完整路径（如 `C:\clips\口播毛片.mp4`），原样写入工程文件素材引用，草稿/工程导入后直接识别素材。`outputs` 含 `project` 时必填；长度 ≤ 1024，服务端不校验存在性、不做路径转换
`struct_meta`	`object`	否	`{}`	同工程文件生成：含 `capcut_draft_path`（你本机的草稿落盘目录）。缺省时剪映 / CapCut 的草稿元信息（`*_meta`）无法产出

render 对象

字段	类型	默认值	说明
`codec`	`string`	`h264`	视频编码器，当前仅支持 `h264`
`crf`	`integer`	`18`	画质参数，14（高质量）~ 28（小体积）
`audio_crossfade_ms`	`integer`	`8`	切点音频淡化毫秒数（0 ~ 50），消除接缝爆音；`0` 为硬切

rhythm_preset 节奏预设表（各档完整参数包）

参数	`steady` 稳健	`concise` 精练	`compact` 紧凑	缺省（不传）
适用场景	讲述、教学、操作演示	自媒体中视频、长视频	短视频、广告	通用
风格系数（自适应模式：对本人节奏的缩放）	×1.25	×1.0	×0.5	×1.0
`、` / `，` / `；`	0.18 / 0.25 / 0.36	0.12 / 0.18 / 0.26	0.06 / 0.08 / 0.12	0.15 / 0.20 / 0.30
`：` / `—`	0.45 / 0.55	0.32 / 0.40	0.15 / 0.18	0.35 / 0.45
`。` `！` / `？`	0.55 / 0.60	0.40 / 0.45	0.18 / 0.20	0.45 / 0.50
`……` / `paragraph`	0.75 / 1.20	0.55 / 0.90	0.25 / 0.40	0.60 / 1.00
`intra_gap_max` / `intra_gap_target`	0.45 / 0.15	0.35 / 0.10	0.25 / 0.05	0.35 / 0.10
`pad_in` / `pad_out`	0.05 / 0.10	0.05 / 0.08	0.03 / 0.05	0.05 / 0.08

punctuation_breaks 默认值（未选预设时的基线，即上表「缺省」列）

标点	默认停顿（秒）	标点	默认停顿（秒）
`，`	0.20	`。`	0.45
`、`	0.15	`！`	0.45
`；`	0.30	`？`	0.50
`：`	0.35	`—`	0.45
`……`	0.60	`paragraph`（文稿换行）	1.00

💡 节奏调试技巧：先选最接近内容类型的预设，再用散参数逐项微调（如 rhythm_preset: "compact" + {"。": 0.3} 在紧凑基础上单独放宽句号）。report.rhythm_preset 会回显实际采用的预设，便于对照。同一份毛片可反复创建任务对比节奏。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_oral_cut \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "78246108192718854",
    "script": "最近你一定刷到过这样的内容：CCD相机、颗粒感滤镜……（文稿全文）",
    "outputs": ["timeline", "project", "video"],
    "project_formats": ["jianying", "xml"],
    "source_path": "C:\\clips\\口播毛片.mp4",
    "struct_meta": {"capcut_draft_path": "C:\\Users\\Me\\AppData\\Local\\JianyingPro\\User Data\\Projects\\com.lveditor.draft\\20260611"},
    "render": {"crf": 18, "audio_crossfade_ms": 8},
    "punctuation_breaks": {"。": 0.4, "paragraph": 0.8}
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178300",
    "task_type": "video_oral_cut",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/video_oral_cut/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key）

响应参数（output_result）

参数名	类型	说明
`timeline`	`object`	剪辑时间线（通用时间线结构，详见下文）
`report`	`object`	剪辑报告（剪了什么、为什么剪，详见下文）
`files`	`array`	可选产物文件列表（`outputs` 含 `project` / `video` 时出现）
`errors`	`object`	可选产物的局部失败原因（部分成功时非空，键如 `project` / `video`）

timeline 结构

与工程文件生成 / 时间线渲染共用同一数据模型：单条视频轨 + 单条音频轨（同源同切点），track_timeline 中每个片段为一段保留的口播。material_map 同时包含：

字段	说明
`path`	`{素材ID: 本地完整路径}`（= 入参 `source_path` 原样值），剪辑软件直接识别；未传 `source_path` 时退化为文件名占位
`file_id`	`{素材ID: 平台文件ID}`，可直接喂给时间线渲染接口
`duration` / `video_rate` / `video_size`	源视频元数据

report 结构

字段	类型	说明
`final_script`	`string`	实际采用的终稿（有稿 = 入参文稿；无稿 = 智能重建结果）
`script_source`	`string`	`user`（用户提供）/ `rebuilt`（智能重建）
`dropped`	`array`	剔除片段列表，元素 `{start, end, asr_text, reason}`；`reason` 取值：`retake`（被后次重读覆盖）/ `misread`（口误、弃读或终稿外内容）
`uncovered_script`	`array`	终稿中未在毛片里找到对应实拍的文本段（疑似漏读），剪辑以实拍为准
`review_points`	`array`	建议人工复核的位置，元素 `{time, note}`（如保留片段识别置信度偏低）
`insufficient_breaks`	`array`	源素材留白不足、停顿未达设定值的位置，元素 `{time, want, got}`
`rhythm_preset`	`string` \| `null`	实际采用的节奏预设名；未用预设为 `null`
`adaptive_rhythm`	`boolean`	自适应节奏实际生效与否（素材过短、停顿样本不足时自动回退固定表并为 `false`）
`pause_profile`	`object`	（仅自适应生效时）说话人停顿画像 `{类: {median, p75, n}}`，调参参照
`analysis_degraded`	`boolean`	智能分析临时不可用、已降级纯机械规则时为 `true`（任务仍正常完成）
`suspect_omissions`	`array`	（仅 `visual_assist=true`）疑似漏识别区间：`{start, end, overlap, recovered}`；`overlap` 为画面说话重叠率，`recovered` 表示是否已找回文字
`stt_recovered`	`array`	（仅 `visual_assist=true`）找补回的文字：`{start, end, text}`，已自动合并进剪辑结果
`visual_assist_degraded`	`boolean`	（仅 `visual_assist=true`）画面检测临时不可用、已按未开启处理时为 `true`（任务仍正常完成）
`coverage`	`number`	终稿覆盖率 0 ~ 1；低于 0.6 时额外返回 `low_coverage: true`，提示文稿与实拍可能严重不符
`duration_before`	`number`	剪辑前时长（秒）
`duration_after`	`number`	剪辑后时长（秒）

files[] 元素

字段	类型	说明
`type`	`string`	`project`（工程文件）/ `video`（渲染成片）
`format`	`string`	工程：`xml` / `fcpxml` / `otio` / `gtrk` / `jianying_draft` / `jianying_meta` / `capcut_draft` / `capcut_meta`；成片：`mp4`
`file_id`	`string`	产物文件 ID
`download_url`	`string`	下载路径
`filename`	`string`	建议文件名（草稿文件需按此命名放入草稿文件夹）
`duration`	`number`	（仅 `type=video`）成片时长（秒）

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178300",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "timeline": {
        "video_size": [1280, 720],
        "video_rate": 30,
        "video_track": [{"track_timeline": [
          {"clip_id": "78246108192718854", "clip_st": 18.50, "track_st": 0.0, "duration": 9.55},
          {"clip_id": "78246108192718854", "clip_st": 28.48, "track_st": 9.55, "duration": 0.64}
        ]}],
        "audio_track": [{"track_timeline": [
          {"clip_id": "78246108192718854", "clip_st": 18.50, "track_st": 0.0, "duration": 9.55},
          {"clip_id": "78246108192718854", "clip_st": 28.48, "track_st": 9.55, "duration": 0.64}
        ]}],
        "material_map": {
          "path": {"78246108192718854": "C:\\clips\\口播毛片.mp4"},
          "file_id": {"78246108192718854": "78246108192718854"},
          "duration": {"78246108192718854": 114.7},
          "video_rate": {"78246108192718854": 30},
          "video_size": {"78246108192718854": [1280, 720]}
        }
      },
      "report": {
        "final_script": "最近你一定刷到过这样的内容：CCD相机……",
        "script_source": "user",
        "dropped": [
          {"start": 7.73, "end": 17.33, "asr_text": "最近你一定刷到过……（第一遍）", "reason": "retake"},
          {"start": 107.89, "end": 110.29, "asr_text": "而这种感觉正在以一种因你方", "reason": "retake"}
        ],
        "uncovered_script": ["十三年"],
        "review_points": [],
        "insufficient_breaks": [],
        "analysis_degraded": false,
        "coverage": 0.982,
        "duration_before": 114.7,
        "duration_after": 68.59
      },
      "files": [
        {"type": "project", "format": "jianying_draft", "file_id": "537489015178301", "download_url": "/download/b1/537489015178301.json", "filename": "draft_content.json"},
        {"type": "video", "format": "mp4", "file_id": "537489015178302", "download_url": "/download/b2/537489015178302.mp4", "filename": "oral_cut.mp4", "duration": 68.59}
      ],
      "errors": {}
    },
    "create_time": "2026-06-11T08:00:00Z",
    "update_time": "2026-06-11T08:03:10Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`file_id` 缺失	补充必填参数
`6004`	404	文件不存在	检查 `file_id` 是否正确
`6014`	400	文件类型与任务不匹配（需视频文件）	上传视频格式文件
`6016`	400	业务参数非法（`outputs` / `project_formats` 越界、`script` 长度超限、节奏参数越界等，响应中附具体原因）	按响应提示修正参数
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6201`	402	配额不足	购买配额包或充值
`6202`	402	余额不足	前往仪表盘充值

使用限制

单文件单机位：当前版本处理单条口播毛片；多机位混剪暂不支持。
有稿模式质量最佳：主推中文口播。无稿模式由智能分析重建终稿（尽力而为），重建结果会在 report.final_script 中返回，便于核对。
按输入时长计费：以毛片时长（分钟）计费；选择 project / video 产物不额外加价。
核心产物保障：timeline + report 产不出时任务才会失败（自动退款）；工程文件与成片为衍生产物，单项失败不影响任务完成，失败原因记录在 errors 中。
工程文件素材引用：草稿/工程中的素材路径取自入参 source_path（原样写入），请确保该路径在你的剪辑环境中真实有效（即上传毛片前它在本机的位置）；产出剪映 / CapCut 可直接打开的完整草稿还需提供 struct_meta.capcut_draft_path。
剪辑以实拍为准：文稿仅作对齐参照；实拍漏读的内容不会无中生有，漏读段落在 report.uncovered_script 中提示。
视觉辅助找补（visual_assist）：用画面说话检测保护疑似漏识别的段落不被误剪并尝试找回文字；找不回时仅保护不剪并在 review_points 提示人工复核，绝不凭空生成内容。需要画面中说话人面部基本可见；处理耗时增加（与主识别并行，约为两者较大值），不额外计费。