面向开发者的视频拼接 API：通过 REST 合并 MP4、MOV 和 AVI

面向开发者的视频拼接 API：通过 REST 合并 MP4、MOV 和 AVI

视频流水线经常从多个来源接收素材。移动应用可能上传 MP4，相机集成可能提供 MOV，旧档案中还可能保留 AVI 或 MPEG。如果下游系统需要一个可预测的媒体文件，每个集成团队都会重复检查输入、规范化、拼接并暴露下载结果的工作。VideoConcat 以异步 REST 视频拼接 API 的形式提供这项能力。

端点和请求模型

经过身份验证的客户端向 POST /api/files/start-process 发送 multipart 请求。设置 actionName=VideoConcat，将 2 到 15 个视频放入 file0 到 file14，并按照公开示例发送 parameters=[] 与 async=true。也可以在 fileUrl 中提供公开 URL，多个 URL 用 | 分隔；上传文件和 URL 可以组合。完整示例与响应契约见 VideoConcat API 文档。

初始响应是处理记录，不是成品媒体。请保存 id 和 trackingUrl，然后使用同一个 Bearer JWT 轮询 /api/actions/get-action-infos/{id}，直到处理完成。这样就不用在视频规范化和编码期间一直占用 HTTP 请求。

为什么要异步

一小组兼容片段可能很快完成，但较大、较长或高分辨率的素材需要更多计算。异步合并视频 API 允许应用确认请求、保存流程 ID，再从状态端点更新自己的任务状态。队列 worker 可以独立于发起请求的网页完成处理。

请把返回的流程 ID 当作状态引用，而不是授权凭证。每次查询状态或下载都要保留已认证的用户上下文，并使用服务器提供的结果链接。调用者仅仅知道一个整数 ID，并不应因此获得结果访问权。

可预测的输出

拼接前，VideoConcat 会规范化每个来源。支持的格式包括 3GP、AVI、FLV、M4V、MKV、MOV、MP4、MPEG、MPG、OGV、TS、WebM 和 WMV，同一次请求可以混用扩展名。输出目标是最高 1920×1080 的共同分辨率、每秒 30 帧、H.264 视频和 AAC 音频。比例不同时使用加黑边保留原画面；没有音频的输入会补充静音音轨。

成功响应提供一个可下载的 MP4，方便交给转码队列、素材管理器、发布流程或客户门户。应用仍然需要判断片段的业务含义，并决定是否需要字幕、品牌元素或进一步剪辑；API 解决的是拼接和规范化，不是编辑审批。

验证与所有权边界

服务器会检查输入数量、真实媒体内容、MIME 信息、所有权和限制。每个视频最多 100 MB、10 分钟；完整请求最多 1 GB、30 分钟，并且必须有 2 到 15 个视频。这些规则不依赖客户端扩展名、JavaScript 或声明的内容类型。

clip.mp4 这样的文件名不能证明字节内容是有效 MP4，文件选择器也不是授权边界。只发送认证账户拥有的文件，安全保存 JWT，把稳定的验证错误当作输入错误处理，不要无限重试。公开 URL 也应当是应用获准处理的来源。

按量计费与重试

成功处理收费 15 tokens，验证失败不收费。任务系统应区分请求被拒绝、处理中、处理失败和处理成功。轮询超时不应直接触发第二次处理；请先重新获取已有流程的状态。

保存流程 ID，采用有界轮询和适当退避。报告成功后保存结果引用，并通过认证的结果流程下载。如果自己的 webhook 或队列收到重复通知，也应让该消费者具备幂等性。

适合哪些集成

常见场景包括合并客户上传的片段、从多个摄像机制作审核副本、为内容管理系统准备单一交付文件，以及在归档前拼接公开培训片段。应用可以接受来自不同路径的 MP4 和 MOV，而不用让用户学习 FFmpeg 或桌面剪辑。

multipart 示例、状态响应和下载细节请查看 VideoConcat REST 文档。当您需要把 MP4、MOV、AVI 或其他支持的素材合成一个规范化 MP4 时，这是一份小而易追踪的异步契约。