媒体处理接口

目录

1. 简介
2. 核心API接口
3. 视频处理接口
4. 音频处理接口
5. 图片处理接口
6. 贴纸处理接口
7. 草稿管理接口
8. 错误处理
9. 最佳实践

简介

对于寻求将自动化工作流与剪映（CapCut）专业视频编辑能力深度集成的开发者而言，CapCut Mate 提供了一个理想的解决方案。这是一个基于 FastAPI 构建的、面向开发者的媒体处理 API 服务，旨在成为连接外部系统与剪映生态的桥梁。

该服务支持对视频、音频、图片及贴纸等多种媒体素材进行批量处理，并提供了时间轴编排与多轨道控制等核心编辑功能。简而言之，它通过一套标准化的 RESTful API，使开发者能够以编程方式将各类素材高效集成至剪映项目中，从而实现视频内容创作的自动化与流程化。

核心API接口

整个系统严格遵循 RESTful API 设计规范，接口定义清晰，响应格式统一。开发者主要交互的核心接口可分为以下几类：

• 草稿管理: 作为所有编辑操作的容器，提供草稿的创建 (/create_draft)、保存 (/sa ve_draft) 与查询 (/get_draft) 功能。
• 媒体添加: 功能核心模块，支持视频 (/add_videos)、音频 (/add_audios)、图片 (/add_images) 及贴纸 (/add_sticker) 的批量导入。
• 视频生成: 负责最终成片的渲染与导出，包括启动生成任务 (/gen_video) 和查询任务状态 (/gen_video_status)。

视频处理接口

接口定义

视频处理接口功能最为全面，支持将多个视频文件批量添加至指定剪映草稿，并允许进行精细的视觉参数调整。

请求参数

• draft_url: 必需，目标操作草稿的唯一访问地址。
• video_infos: 必需，一个 JSON 字符串数组，包含所有待添加视频的详细信息。
• alpha: 视频透明度，取值范围 0（全透明）到 1（不透明），默认值为 1.0。
• scale_x/scale_y: 分别控制视频在 X 轴和 Y 轴方向的缩放比例，建议范围 0.1 至 5.0，默认 1.0（原始尺寸）。
• transform_x/transform_y: 用于调整视频在画布中的位置坐标，单位为像素。

视频信息结构

每个视频的具体配置封装在 video_infos 数组的对象中，结构示例如下：

{
  "video_url": "https://example.com/video.mp4",
  "width": 1920,
  "height": 1080,
  "start": 0,
  "end": 10000000,
  "duration": 10000000,
  "mask": "",
  "transition": "",
  "transition_duration": 500000,
  "volume": 1.0
}

该结构不仅定义了视频源地址和分辨率，还允许精确控制其在时间轴上的入点 (start)、出点 (end)、持续时长，以及是否应用转场特效和音量大小。

处理流程

一个视频从 API 请求到成功嵌入草稿，其内部处理流程如下：

flowchart TD
Start([开始处理]) --> Parse[解析视频信息]
Parse --> Validate{验证参数}
Validate --> |有效| Download[下载视频文件]
Validate --> |无效| Error[返回错误]
Download --> CreateMaterial[创建视频素材]
CreateMaterial --> CreateSegment[创建视频片段]
CreateSegment --> AddTransition{添加转场效果}
AddTransition --> |有转场| ApplyTransition[应用转场]
AddTransition --> |无转场| SkipTransition[跳过转场]
ApplyTransition --> AddTrack[添加到轨道]
SkipTransition --> AddTrack
AddTrack --> Sa veDraft[保存草稿]
Sa veDraft --> Return[返回结果]
Error --> End([结束])
Return --> End

概括而言，系统首先会解析并验证传入的参数，随后下载远程视频文件，接着在剪映引擎中创建对应的媒体素材与时间轴片段，根据配置决定是否添加转场效果，最终将处理完成的片段置入相应轨道并保存草稿状态。

音频处理接口

接口定义

音频处理接口设计简洁高效，核心功能是批量将音频文件添加至草稿的音频轨道。

请求参数

• draft_url: 必需，目标草稿 URL。
• audio_infos: 必需，包含音频文件信息的 JSON 字符串数组。

音频信息结构

每个音频对象的配置主要关注音频源、时长及在时间轴上的位置：

{
  "audio_url": "https://example.com/audio.mp3",
  "duration": 23184000,
  "start": 0,
  "end": 23184000
}

处理流程

音频的处理流程侧重于文件获取与轨道集成，各组件间的交互序列如下：

sequenceDiagram
participant API as API接口
participant Service as 服务层
participant Download as 下载器
participant Draft as 草稿引擎
participant Track as 音频轨道
API->>Service : add_audios()
Service->>Download : 下载音频文件
Download-->>Service : 返回本地路径
Service->>Draft : 创建音频素材
Service->>Track : 添加到音频轨道
Track-->>Service : 返回轨道信息
Service-->>API : 标准化响应

图片处理接口

接口定义

图片处理接口允许将静态图片作为动态视频片段插入时间轴，并支持丰富的视觉调整参数。

请求参数

• draft_url: 必需，目标草稿 URL。
• image_infos: 必需，图片信息数组（JSON 字符串）。
• alpha: 透明度（0-1），默认 1.0。
• scale_x/scale_y: 缩放比例。
• transform_x/transform_y: 位置偏移（像素）。

图片信息结构

每个图片对象的配置项非常全面，可控制显示时长、位置、入场动画及转场效果：

{
  "image_url": "https://example.com/image.png",
  "width": 1920,
  "height": 1080,
  "start": 0,
  "end": 5000000,
  "duration": 5000000,
  "animation": "淡入淡出",
  "transition": "溶解",
  "transition_duration": 500000,
  "alpha": 1.0
}

贴纸处理接口

接口定义

贴纸接口用于在视频的特定时间段叠加动态或静态图形元素，例如表情包、标签或装饰性图案。

请求参数

• draft_url: 必需，目标草稿 URL。
• sticker_id: 必需，剪映平台内置的贴纸资源标识符。
• start/end: 必需，贴纸在时间轴上的开始与结束时间（微秒）。
• scale: 整体缩放比例（0.1-5.0），默认 1.0。
• transform_x/transform_y: 在画布上的位置偏移（像素）。

贴纸管理

系统内部对贴纸的请求与响应有明确的数据模型定义。以下类图展示了核心对象的结构与关系：

classDiagram
class StickerRequest {
+string draft_url
+string sticker_id
+integer start
+integer end
+float scale
+integer transform_x
+integer transform_y
}
class StickerResponse {
+string draft_url
+string sticker_id
+string track_id
+string segment_id
+integer duration
}
StickerRequest --> StickerResponse : "生成"

草稿管理接口

草稿是所有媒体编辑操作的容器与上下文环境。高效管理草稿是确保自动化流程顺畅运行的基础。

创建草稿

接口: POST /v1/create_draft

请求参数

• width: 视频画布宽度，默认 1920 像素。
• height: 视频画布高度，默认 1080 像素。

响应参数

• draft_url: 新创建草稿的唯一访问 URL，后续所有操作均基于此 URL。
• tip_url: 可选的帮助文档 URL，提供更多使用指引。

保存草稿

接口: POST /v1/sa ve_draft

在完成一系列添加、删除或修改操作后，需调用此接口以持久化草稿的当前状态。

请求参数

• draft_url: 需要保存的草稿 URL。

响应参数

• draft_url: 保存成功后返回的草稿 URL（通常与请求一致）。

获取草稿

接口: GET /v1/get_draft

此接口用于获取指定草稿的详细信息或其所包含的媒体文件列表。

请求参数

• draft_id: 草稿的唯一标识 ID。

响应参数

• files: 该草稿中包含的所有媒体文件列表。

错误处理

任何完善的系统都可能遇到异常情况。一套清晰的错误分类与处理指南，能帮助开发者快速定位并解决问题。

常见错误类型

草稿相关错误

• INVALID_DRAFT_URL: 提供的草稿 URL 格式错误或已过期失效。
• DRAFT_NOT_FOUND: 系统无法找到对应的草稿文件，可能已被删除。
• DRAFT_SA VE_FAILED: 草稿保存失败，可能由于磁盘空间不足或文件权限问题导致。

媒体处理错误

• VIDEO_ADD_FAILED: 添加视频失败，常见原因包括格式不支持、文件损坏或编码问题。
• AUDIO_ADD_FAILED: 添加音频失败。
• IMAGE_ADD_FAILED: 添加图片失败。
• STICKER_ADD_FAILED: 添加贴纸失败，通常由于贴纸 ID 不存在或无效。

调试建议

1. 检查网络连接: 首先确认提供的媒体文件 URL 是公开可访问的，且未被防火墙或安全策略拦截。
2. 验证文件格式: 确保视频、音频、图片的格式在剪映的支持列表内。常见的 MP4、MOV、MP3、WAV、PNG、JPG 格式通常兼容性良好。
3. 检查时间轴配置: 仔细核对 start 和 end 时间参数，确保逻辑正确（结束时间晚于开始时间），并检查不同素材的时间段是否存在非预期的重叠或冲突。
4. 查看日志文件: 当 API 返回的错误信息不够明确时，查阅服务端的详细运行日志与错误堆栈跟踪，是定位复杂问题的关键步骤。

最佳实践

遵循以下实践原则，可以使您的集成更加稳定、高效。

性能优化

• 批量处理: 尽可能使用批量添加接口（如 /add_videos），一次性传入多个媒体信息，而非为每个文件发起单独请求，这能显著减少网络开销与整体延迟。
• 缓存策略: 对于需要频繁使用的远程媒体文件，建议在本地或中间层实施缓存机制，避免每次处理都重新下载，提升处理速度。
• 资源复用: 在同一草稿中，若多个位置使用相同的背景音乐或图片素材，应尽量复用同一个素材引用，而非重复添加，以节省资源。
• 并发控制: 系统虽支持并发请求，但同时处理大量高分辨率视频可能消耗大量内存与 CPU。请根据服务器实际性能，合理控制并发任务数量。

参数验证

• 时间参数: 在调用接口前，务必在客户端校验 end 时间大于 start 时间，避免产生无效请求。
• 数值范围: 对于透明度 (alpha)、缩放比例 (scale) 等参数，确保其数值在接口文档允许的有效范围内。
• URL有效性: 发送请求前，可尝试对媒体文件的 URL 发起 HEAD 请求，预先确认其可访问性与有效性。
• 文件格式: 明确了解系统支持的媒体格式列表。对于用户上传的内容，建议在前端或网关层进行格式过滤与校验。

错误恢复

• 重试机制: 针对网络超时、服务暂时不可用等瞬时错误，建议实现带有指数退避算法的重试逻辑，以提高请求的最终成功率。
• 降级策略: 在设计应用逻辑时，需考虑当某个视频添加失败时，是中止整个任务，还是跳过该文件继续处理其他媒体？后者通常能提供更佳的用户体验和任务完成率。
• 日志记录: 除了依赖系统的错误返回，建议在您的应用层也记录详细的操作日志，包括请求参数、响应结果及耗时，这对于后期排查线上问题至关重要。