【开源剪映小助手】编辑效果接口编辑效果接口目录简介核心API接口数据模型设计业务流程分析参数配置详解错误处

编辑效果接口

简介

编辑效果接口是CapCut Mate的核心功能模块，负责处理基础视频编辑效果。基于FastAPI框架实现，通过RESTful API提供服务，支持特效应用、遮罩效果、关键帧动画、文字样式等编辑功能。

系统聚焦核心编辑效果，提供简洁高效的API，方便开发者快速集成视频编辑能力。所有接口使用统一响应格式，包含完整的错误处理和参数验证机制。

核心API接口

编辑效果接口包含以下核心API端点：

接口名称	HTTP方法	路径	功能描述
添加特效	POST	`/v1/add_effects`	向草稿添加视频特效
添加关键帧	POST	`/v1/add_keyframes`	为片段添加关键帧动画
添加遮罩	POST	`/v1/add_masks`	为片段添加遮罩效果
添加文本样式	POST	`/v1/add_text_style`	创建富文本样式

API响应统一格式

所有API响应使用统一的JSON格式，包含标准的响应头和数据结构：

sequenceDiagram
participant Client as 客户端
participant Router as 路由器
participant Service as 服务层
participant Response as 响应处理器
Client->>Router : HTTP请求
Router->>Service : 调用业务逻辑
Service-->>Router : 业务结果
Router->>Response : 标准化响应
Response-->>Client : 统一格式响应

数据模型设计

系统使用Pydantic模型定义API参数，确保数据验证和类型安全：

classDiagram
class AddEffectsRequest {
+string draft_url
+string effect_infos
}
class AddKeyframesRequest {
+string draft_url
+string keyframes
}
class AddMasksRequest {
+string draft_url
+string[] segment_ids
+string name
+int X
+int Y
+int width
+int height
+int feather
+int rotation
+bool invert
+int roundCorner
}
class AddTextStyleRequest {
+string text
+string keyword
+int font_size
+string keyword_color
+int keyword_font_size
}
class EffectItem {
+string effect_title
+int start
+int end
}
class KeyframeItem {
+string segment_id
+string property
+float offset
+float value
}
AddEffectsRequest --> EffectItem
AddKeyframesRequest --> KeyframeItem

业务流程分析

特效添加流程

sequenceDiagram
participant Client as 客户端
participant Service as 特效服务
participant Cache as 草稿缓存
participant Draft as 草稿文件
participant Track as 特效轨道
Client->>Service : 添加特效请求
Service->>Service : 验证草稿URL
Service->>Cache : 获取草稿实例
Cache-->>Service : 返回草稿对象
Service->>Service : 解析特效信息
Service->>Service : 查找特效类型
Service->>Draft : 创建特效片段
Draft->>Track : 添加到特效轨道
Track-->>Draft : 确认添加
Draft-->>Service : 返回片段ID
Service-->>Client : 返回特效信息

关键帧添加流程

flowchart TD
Start([关键帧添加请求]) --> ValidateDraft[验证草稿URL]
ValidateDraft --> ParseData[解析关键帧数据]
ParseData --> LoopSegments[遍历关键帧项]
LoopSegments --> FindSegment[查找目标片段]
FindSegment --> ValidateSegment{验证片段类型}
ValidateSegment --> |视频片段| AddKeyframe[添加关键帧]
ValidateSegment --> |其他类型| SkipSegment[跳过并记录]
AddKeyframe --> UpdateAffected[更新受影响片段列表]
SkipSegment --> NextItem[处理下一个关键帧]
UpdateAffected --> NextItem
NextItem --> CheckComplete{所有关键帧处理完?}
CheckComplete --> |否| LoopSegments
CheckComplete --> |是| SaveDraft[保存草稿]
SaveDraft --> End([返回响应])

遮罩添加流程

flowchart TD
Start([遮罩添加请求]) --> ValidateParams[验证请求参数]
ValidateParams --> LoadDraft[加载草稿文件]
LoadDraft --> FindMaskType[查找遮罩类型]
FindMaskType --> LoopSegments[遍历片段ID列表]
LoopSegments --> FindSegment[查找片段]
FindSegment --> ValidateSegment{验证片段类型}
ValidateSegment --> |视频片段| CheckExistingMask{检查是否已有遮罩}
ValidateSegment --> |其他类型| SkipSegment[跳过并记录]
CheckExistingMask --> |已有遮罩| ReturnExisting[返回现有遮罩ID]
CheckExistingMask --> |无遮罩| AddMask[添加新遮罩]
ValidateSegment --> |视频片段| AddMask
AddMask --> UpdateLists[更新统计和列表]
ReturnExisting --> UpdateLists
SkipSegment --> UpdateLists
UpdateLists --> NextSegment[处理下一个片段]
NextSegment --> CheckComplete{所有片段处理完?}
CheckComplete --> |否| LoopSegments
CheckComplete --> |是| SaveDraft[保存草稿]
SaveDraft --> End([返回响应])

参数配置详解

特效参数配置

参数名称	类型	必填	默认值	说明
draft_url	string	是	无	草稿文件URL，包含draft_id参数
effect_infos	string	是	无	JSON字符串格式的特效信息数组

特效信息数组中的每个元素包含：

effect_title: 特效名称，必填
start: 开始时间（微秒），必填
end: 结束时间（微秒），必填

关键帧参数配置

参数名称	类型	必填	默认值	说明
draft_url	string	是	无	草稿文件URL，包含draft_id参数
keyframes	string	是	无	JSON字符串格式的关键帧信息数组

关键帧信息数组中的每个元素包含：

segment_id: 目标片段ID，必填
property: 动画属性类型，必填
offset: 时间偏移（微秒），必填
value: 属性值，必填

支持的动画属性类型：

KFTypePositionX, KFTypePositionY: 位置属性
KFTypeScaleX, KFTypeScaleY: 缩放属性
KFTypeRotation: 旋转属性
KFTypeAlpha: 透明度属性
UNIFORM_SCALE: 统一缩放
KFTypeSaturation, KFTypeContrast, KFTypeBrightness: 颜色属性
KFTypeVolume: 音量属性

遮罩参数配置

参数名称	类型	必填	默认值	说明
draft_url	string	是	无	草稿文件URL，包含draft_id参数
segment_ids	array	是	无	要应用遮罩的片段ID数组
name	string	否	"线性"	遮罩类型名称，默认支持6种类型
X, Y	int	否	0	遮罩中心坐标（像素）
width, height	int	否	512	遮罩尺寸（像素）
feather	int	否	0	羽化程度（0-100）
rotation	int	否	0	旋转角度（度）
invert	bool	否	false	是否反转遮罩
roundCorner	int	否	0	圆角半径（0-100）

支持的遮罩类型：

线性, 镜面, 圆形, 矩形, 爱心, 星形

文本样式参数配置

参数名称	类型	必填	默认值	说明
text	string	是	无	要处理的文本内容
keyword	string	是	无	关键词，多个用"	"分隔
font_size	int	否	12	普通文本字体大小
keyword_color	string	否	"#ff7100"	关键词文本颜色（十六进制）
keyword_font_size	int	否	15	关键词字体大小

错误处理机制

系统实现了完整的错误处理机制，确保API调用的稳定性和可靠性：

错误类型分类

错误类型	错误码	触发条件	处理方式
草稿URL无效	400	draft_id缺失或不在缓存中	返回INVALID_DRAFT_URL错误
参数格式错误	422	JSON解析失败或字段缺失	返回INVALID_EFFECT_INFO等错误
特效不存在	404	特效名称无法匹配	返回EFFECT_NOT_FOUND错误
片段不存在	404	片段ID无法找到	返回SEGMENT_NOT_FOUND错误
遮罩类型错误	404	遮罩名称无法匹配	返回MASK_NOT_FOUND错误
片段类型不支持	400	非视频片段添加遮罩	返回INVALID_SEGMENT_TYPE错误
内部处理错误	500	服务器异常或保存失败	返回对应业务错误

错误响应格式

{
    "error": {
        "code": "INVALID_DRAFT_URL",
        "message": "无效的草稿URL或草稿不存在",
        "details": {}
    }
}

性能优化建议

缓存策略

系统使用多层缓存提升性能：

草稿缓存：内存缓存存储活跃草稿实例
元数据缓存：缓存特效和遮罩类型元数据
响应缓存：缓存静态数据

并发处理

系统支持高并发请求：

异步请求处理
连接池管理
资源限制控制

批量操作优化

处理大量数据时建议：

控制单次请求的数据量
使用批量API减少HTTP请求次数
实现适当的重试机制

使用示例

添加特效示例

// 请求示例
const effectRequest = {
    draft_url: "https://example.com/get_draft?draft_id=123456789",
    effect_infos: JSON.stringify([
        {
            effect_title: "录制边框 III",
            start: 0,
            end: 5000000
        }
    ])
};

// 响应示例
{
    draft_url: "https://example.com/get_draft?draft_id=123456789",
    track_id: "effect_track_987654321",
    effect_ids: ["effect_123"],
    segment_ids: ["segment_456"]
}

添加关键帧示例

// 请求示例
const keyframeRequest = {
    draft_url: "https://example.com/get_draft?draft_id=123456789",
    keyframes: JSON.stringify([
        {
            segment_id: "segment_456",
            property: "KFTypePositionX",
            offset: 2500000,
            value: 0.5
        }
    ])
};

添加遮罩示例

// 请求示例
const maskRequest = {
    draft_url: "https://example.com/get_draft?draft_id=123456789",
    segment_ids: ["segment_456"],
    name: "圆形",
    X: 1920,
    Y: 1080,
    width: 1000,
    height: 1000,
    feather: 50
};

创建文本样式示例

// 请求示例
const textStyleRequest = {
    text: "快乐|顶级思维",
    keyword: "快乐|顶级思维",
    font_size: 15,
    keyword_color: "#ff7100",
    keyword_font_size: 18
};

// 响应示例
{
    text_style: "{\"text\":\"快乐|顶级思维\",\"styles\":[{\"fill\":{\"content\":{\"solid\":{\"color\":[1.0,1.0,1.0]}}},\"range\":[0,7],\"size\":15,\"font\":{\"id\":\"\",\"path\":\"\"}}]}"
}

总结

编辑效果接口提供了简洁高效的视频编辑功能集合，具有以下特点：

功能聚焦：专注于核心编辑效果功能，避免功能冗余
接口简洁：提供最少必要的API端点，降低学习成本
类型安全：使用Pydantic模型确保参数验证和类型安全
错误处理：完整的错误处理机制，提供清晰的错误信息
性能优化：多层缓存和并发处理机制提升系统性能

系统为视频编辑应用提供了稳定可靠的技术基础，支持特效应用、关键帧动画、遮罩效果、文字样式等核心编辑功能，能够满足大多数视频编辑场景的需求。通过统一的API接口和标准化的响应格式，开发者可以快速集成和扩展编辑效果功能。