【开源剪映小助手】编辑效果接口

编辑效果接口

目录

1. 简介
2. 核心API接口
3. 数据模型设计
4. 业务流程分析
5. 参数配置详解
6. 错误处理机制
7. 性能优化建议
8. 使用示例
9. 总结

简介

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

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

核心API接口

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

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([返回响应])

参数配置详解

特效参数配置

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

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

关键帧参数配置

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

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

支持的动画属性类型：

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

遮罩参数配置

支持的遮罩类型：

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

文本样式参数配置

错误处理机制

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

错误类型分类

错误响应格式

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

性能优化建议

缓存策略

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

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

并发处理

系统支持高并发请求：

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

批量操作优化

处理大量数据时建议：

• 控制单次请求的数据量
• 使用批量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\":\"\"}}]}"
}

总结

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

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

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