字幕信息生成接口
目录
简介
字幕信息生成接口（/caption_infos）是CapCut Mate项目中的一个核心API端点，专门用于根据文本内容和时间线生成字幕信息。该接口支持多种字幕样式配置、关键词高亮、入场出场动画以及转场效果设置。
新增智能参数修剪和优雅降级机制，当输入参数长度不匹配时，系统会自动以最短长度为准进行处理，而不是直接抛出错误。
本接口的主要功能包括：
- 根据文本列表和时间线数组生成字幕信息
- 支持字体大小、颜色等样式定制
- 提供关键词高亮功能
- 支持入场、循环、出场动画效果
- 配置转场效果和持续时间
- 处理多字幕场景
- 智能参数修剪和优雅降级机制
项目结构
CapCut Mate项目采用模块化架构设计，字幕信息生成功能分布在以下层次：
graph TB
subgraph "API层"
Router[路由层]
Schema[模式定义]
end
subgraph "服务层"
CaptionService[字幕信息服务]
end
subgraph "数据层"
TextSegment[文本片段]
Animation[动画元数据]
Effect[特效元数据]
end
Router --> Schema
Router --> CaptionService
CaptionService --> TextSegment
TextSegment --> Animation
TextSegment --> Effect
核心组件
请求参数模型
字幕信息生成接口的请求参数通过Pydantic模型进行严格验证：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| texts | List[str] | ✅ | - | 文本列表，每个元素对应一个字幕 |
| timelines | List[TimelineItem] | ✅ | - | 时间线数组，与文本列表一一对应 |
| font_size | Optional[int] | ❌ | None | 字体大小 |
| keyword_color | Optional[str] | ❌ | None | 关键词颜色（十六进制格式） |
| keyword_font_size | Optional[int] | ❌ | None | 关键词字体大小 |
| keywords | Optional[List[str]] | ❌ | None | 重点词列表，与文本对应 |
| in_animation | Optional[str] | ❌ | None | 入场动画名称 |
| in_animation_duration | Optional[int] | ❌ | None | 入场动画时长 |
| loop_animation | Optional[str] | ❌ | None | 组合动画名称 |
| loop_animation_duration | Optional[int] | ❌ | None | 组合动画时长 |
| out_animation | Optional[str] | ❌ | None | 出场动画名称 |
| out_animation_duration | Optional[int] | ❌ | None | 出场动画时长 |
| transition | Optional[str] | ❌ | None | 转场名称 |
| transition_duration | Optional[int] | ❌ | None | 转场时长 |
响应模型
接口返回JSON字符串格式的字幕信息，包含以下结构：
classDiagram
class CaptionInfosResponse {
+string infos
+description "JSON字符串格式的字幕信息"
}
class TimelineItem {
+int start
+int end
+description "时间线项，包含开始和结束时间"
}
class CaptionInfo {
+int start
+int end
+string text
+string keyword
+string keyword_color
+int keyword_font_size
+int font_size
+string in_animation
+int in_animation_duration
+string loop_animation
+int loop_animation_duration
+string out_animation
+int out_animation_duration
+string transition
+int transition_duration
}
CaptionInfosResponse --> CaptionInfo : "包含多个字幕信息"
TimelineItem --> CaptionInfo : "与字幕信息关联"
架构概览
字幕信息生成接口遵循标准的三层架构模式：
sequenceDiagram
participant Client as "客户端"
participant Router as "路由层"
participant Service as "服务层"
participant Utils as "工具函数"
Client->>Router : POST /v1/caption_infos
Router->>Router : 参数验证
Router->>Service : 调用caption_infos()
Service->>Service : 智能参数修剪
Service->>Utils : 构建字幕信息
Utils->>Utils : 处理关键词
Utils->>Utils : 应用动画参数
Utils-->>Service : 返回字幕信息列表
Service->>Service : 转换为JSON
Service-->>Router : 返回JSON字符串
Router-->>Client : 响应结果
详细组件分析
字幕信息生成服务
字幕信息生成服务是整个功能的核心实现，现已增强智能参数修剪功能：
flowchart TD
Start([开始]) --> ValidateParams["验证参数"]
ValidateParams --> CheckLength{"检查长度匹配"}
CheckLength --> |不匹配| TrimParams["智能参数修剪"]
CheckLength --> |匹配| InitList["初始化信息列表"]
TrimParams --> MinLen["计算最短长度"]
MinLen --> TruncateTexts["截断texts到最短长度"]
TruncateTexts --> TruncateTimelines["截断timelines到最短长度"]
TruncateTimelines --> LogWarning["记录警告日志"]
LogWarning --> InitList
InitList --> LoopTexts["遍历文本和时间线"]
LoopTexts --> BuildInfo["构建字幕信息"]
BuildInfo --> AddKeyword{"是否有关键词"}
AddKeyword --> |是| SetKeyword["设置关键词"]
AddKeyword --> |否| SkipKeyword["跳过关键词"]
SetKeyword --> AddStyles["添加样式参数"]
SkipKeyword --> AddStyles
AddStyles --> AddAnimations["添加动画参数"]
AddAnimations --> AddTransitions["添加转场参数"]
AddTransitions --> AppendToList["添加到列表"]
AppendToList --> MoreItems{"还有更多项目?"}
MoreItems --> |是| LoopTexts
MoreItems --> |否| ConvertJSON["转换为JSON"]
ConvertJSON --> ReturnResult["返回结果"]
ReturnResult --> End([结束])
智能参数修剪机制
新增智能参数修剪功能，当输入参数长度不匹配时，系统会自动处理：
- 自动检测：检查
texts和timelines数组长度是否相等 - 智能降级：使用
min(len(texts), len(timelines))作为新长度 - 优雅处理：截断较长的数组到最短长度，而不是抛出错误
- 详细日志：记录长度不匹配的警告信息和处理过程
动画效果支持
系统支持多种动画效果，包括入场、循环和出场动画：
classDiagram
class AnimationEffects {
+TextIntro 入场动画
+TextLoopAnim 循环动画
+TextOutro 出场动画
+Transition 转场效果
}
class TextIntro {
+冲屏位移
+展开
+弹入
+渐显
+其他多种效果
}
class TextLoopAnim {
+旋转
+摇摆
+闪烁
+彩虹
+其他多种效果
}
class TextOutro {
+右上弹出
+展开
+渐隐
+溶解
+其他多种效果
}
class Transition {
+推近
+推远
+淡入淡出
+其他多种效果
}
AnimationEffects --> TextIntro
AnimationEffects --> TextLoopAnim
AnimationEffects --> TextOutro
AnimationEffects --> Transition
样式配置系统
字幕样式配置支持丰富的视觉效果：
| 样式属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| font_size | int | 15 | 字体大小（像素） |
| keyword_color | string | "#ff7100" | 关键词高亮颜色 |
| keyword_font_size | int | 15 | 关键词字体大小 |
| text_color | string | "#ffffff" | 文本颜色 |
| alignment | int | 1 | 文本对齐方式（0-5） |
| alpha | float | 1.0 | 文本透明度（0.0-1.0） |
| scale_x | float | 1.0 | 水平缩放比例 |
| scale_y | float | 1.0 | 垂直缩放比例 |
| transform_x | number | 0.0 | X轴位置偏移（像素） |
| transform_y | number | 0.0 | Y轴位置偏移（像素） |
依赖关系分析
核心依赖关系
graph TD
subgraph "外部依赖"
Pydantic[Pydantic验证库]
FastAPI[FastAPI框架]
JSON[JSON序列化]
Logging[日志记录]
end
subgraph "内部模块"
Router[路由模块]
Schema[模式定义]
Service[服务实现]
Logger[日志记录]
end
subgraph "数据模型"
TimelineItem[时间线项]
CaptionInfo[字幕信息]
TextStyle[文本样式]
end
Pydantic --> Schema
FastAPI --> Router
JSON --> Service
Logging --> Logger
Logger --> Service
Router --> Schema
Router --> Service
Schema --> TimelineItem
Service --> CaptionInfo
Service --> TextStyle
数据流依赖
字幕信息生成的数据流遵循严格的依赖顺序：
- 输入验证：Pydantic模型验证请求参数
- 智能修剪：服务层处理参数长度不匹配问题
- 参数处理：字幕信息生成逻辑
- 样式应用：文本样式和动画效果应用
- 输出序列化：JSON格式化输出
性能考虑
时间复杂度分析
字幕信息生成算法的时间复杂度为O(n)，其中n是字幕文本的数量：
- 参数验证：O(1) - Pydantic模型验证
- 长度检查：O(1) - 比较texts和timelines长度
- 智能修剪：O(1) - 计算最短长度和截断操作
- 主循环：O(n) - 遍历每个字幕项
- JSON序列化：O(n) - 序列化所有字幕信息
内存使用优化
- 流式处理：逐个构建字幕信息，避免大量内存占用
- 条件添加：仅在参数存在时添加到字幕信息中
- 字符串处理：使用高效的字符串连接和JSON序列化
- 智能修剪：只截断必要的部分，减少内存分配
批量处理建议
对于大量字幕的处理，建议：
- 分批处理字幕信息
- 使用异步处理机制
- 实施缓存策略
- 优化数据库查询
故障排除指南
常见错误及解决方案
新增智能参数修剪机制后的故障排除指南：
| 错误类型 | 错误信息 | 可能原因 | 解决方案 |
|---|---|---|---|
| 参数验证错误 | texts长度不匹配timelines长度 | 参数长度不一致 | 已解决：系统现在自动以最短长度为准进行处理 |
| JSON序列化错误 | JSON编码失败 | 字符编码问题 | 检查文本编码和特殊字符 |
| 动画参数错误 | 无效的动画名称 | 动画名称不在支持列表中 | 使用系统支持的动画名称 |
| 样式参数错误 | 无效的颜色格式 | 颜色格式不正确 | 使用十六进制颜色格式（如#ffffff） |
| 日志警告 | texts length does not match timelines length | 输入参数长度不匹配 | 查看日志了解自动修剪过程 |
智能参数修剪行为说明
当检测到参数长度不匹配时，系统会执行以下优雅降级过程：
- 自动检测：比较
texts和timelines的长度 - 计算最短长度：使用
min(len(texts), len(timelines)) - 截断处理：将较长的数组截断到最短长度
- 日志记录：记录详细的警告信息，包括原始长度和最终长度
- 继续处理：使用修剪后的参数继续字幕生成过程
调试技巧
- 启用详细日志：查看服务层的日志输出，了解智能修剪过程
- 参数验证：使用Pydantic模型验证输入参数
- 单元测试：运行测试用例验证功能正常
- 边界测试：测试极端情况和边界条件
- 监控日志：关注长度不匹配时的日志警告信息
结论
字幕信息生成接口提供了完整的字幕处理解决方案，现已增强智能参数修剪和优雅降级机制：
优势
- 灵活的参数配置：支持丰富的样式和动画选项
- 严格的参数验证：使用Pydantic确保数据完整性
- 智能参数修剪：自动处理长度不匹配问题，提供优雅降级
- 详细的日志记录：记录处理过程和警告信息
- 高性能处理：线性时间复杂度，适合大批量处理
- 扩展性强：模块化设计便于功能扩展
应用场景
- 视频字幕生成和编辑
- 多语言字幕处理
- 动态字幕效果制作
- 批量字幕信息管理
- 容错性要求较高的应用场景
未来改进方向
- 增加更多动画效果支持
- 优化性能以处理超大字幕集
- 提供更丰富的样式定制选项
- 增强国际化和本地化支持
- 扩展智能修剪功能，支持更多类型的参数验证
附录
使用示例
基本字幕生成
{
"texts": ["欢迎使用字幕功能", "这是第二个字幕"],
"timelines": [
{"start": 0, "end": 284891428},
{"start": 284891428, "end": 579578774}
]
}
带样式的字幕生成
{
"texts": ["关键词高亮示例"],
"timelines": [{"start": 0, "end": 1000000}],
"font_size": 15,
"keyword_color": "#ff0000",
"keyword_font_size": 15,
"keywords": ["关键词"],
"in_animation": "展开",
"out_animation": "闪现"
}
智能参数修剪示例
{
"texts": ["字幕1", "字幕2", "字幕3", "字幕4"],
"timelines": [
{"start": 0, "end": 1000000},
{"start": 1000000, "end": 2000000}
]
}
结果：系统会自动截断到最短长度2，只处理前两个字幕项，并记录相应的警告日志。
API规范
端点：POST /v1/caption_infos
请求头：
- Content-Type: application/json
响应格式：JSON字符串，包含字幕信息数组
状态码：
- 200: 请求成功
- 400: 参数错误
- 500: 服务器内部错误
语言切换机制
语言切换标题已从三级标题升级为二级标题，提升语言切换的可见性
为了提升用户体验，字幕信息生成接口文档采用了统一的语言切换机制。所有文档页面顶部都包含了清晰的语言切换导航，用户可以通过点击链接在中文版和英文版之间快速切换。
语言切换机制的特点：
- 统一的标题层级：所有文档使用二级标题
## 🌐 Language Switch保持一致性 - 直观的导航：提供清晰的中英文版本链接
- 良好的可访问性：确保用户能够轻松找到目标语言版本
- 一致的用户体验：与其他文档保持相同的语言切换模式
这种设计提升了文档的可用性和国际化支持，让用户能够更方便地访问不同语言版本的文档内容。
