字幕信息生成接口
目录
简介
字幕信息生成接口（/caption_infos）是CapCut Mate项目中的一个核心API端点，专门用于根据文本内容和时间线生成字幕信息。该接口支持多种字幕样式配置、关键词高亮、入场出场动画以及转场效果设置。
新增智能参数修剪和优雅降级机制，当输入参数长度不匹配时，系统会自动以最短长度为准进行处理，而不是直接抛出错误。
本接口的主要功能包括：
- 根据文本列表和时间线数组生成字幕信息
- 支持字体大小、颜色等样式定制
- 提供关键词高亮功能
- 支持入场、循环、出场动画效果
- 配置转场效果和持续时间
- 处理多字幕场景
- 智能参数修剪和优雅降级机制
项目结构
CapCut Mate项目采用模块化架构设计，字幕信息生成功能分布在以下层次：
数据层
服务层
API层
路由层
模式定义
字幕信息服务
文本片段
动画元数据
特效元数据
核心组件
请求参数模型
字幕信息生成接口的请求参数通过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字符串格式的字幕信息，包含以下结构：
"包含多个字幕信息"
"与字幕信息关联"
CaptionInfosResponse
+string infos
+description "JSON字符串格式的字幕信息"
TimelineItem
+int start
+int end
+description "时间线项，包含开始和结束时间"
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
架构概览
字幕信息生成接口遵循标准的三层架构模式：
"工具函数" "服务层" "路由层" "客户端" "工具函数" "服务层" "路由层" "客户端" POST /v1/caption_infos 参数验证 调用caption_infos() 智能参数修剪 构建字幕信息 处理关键词 应用动画参数 返回字幕信息列表 转换为JSON 返回JSON字符串 响应结果
详细组件分析
字幕信息生成服务
字幕信息生成服务是整个功能的核心实现，现已增强智能参数修剪功能：
不匹配
匹配
是
否
是
否
开始
验证参数
检查长度匹配
智能参数修剪
初始化信息列表
计算最短长度
截断texts到最短长度
截断timelines到最短长度
记录警告日志
遍历文本和时间线
构建字幕信息
是否有关键词
设置关键词
跳过关键词
添加样式参数
添加动画参数
添加转场参数
添加到列表
还有更多项目?
转换为JSON
返回结果
结束
智能参数修剪机制
新增智能参数修剪功能，当输入参数长度不匹配时，系统会自动处理：
- 自动检测 ：检查
texts和timelines数组长度是否相等 - 智能降级 ：使用
min(len(texts), len(timelines))作为新长度 - 优雅处理：截断较长的数组到最短长度，而不是抛出错误
- 详细日志：记录长度不匹配的警告信息和处理过程
动画效果支持
系统支持多种动画效果，包括入场、循环和出场动画：
AnimationEffects
+TextIntro 入场动画
+TextLoopAnim 循环动画
+TextOutro 出场动画
+Transition 转场效果
TextIntro
+冲屏位移
+展开
+弹入
+渐显
+其他多种效果
TextLoopAnim
+旋转
+摇摆
+闪烁
+彩虹
+其他多种效果
TextOutro
+右上弹出
+展开
+渐隐
+溶解
+其他多种效果
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轴位置偏移（像素） |
依赖关系分析
核心依赖关系
数据模型
内部模块
外部依赖
Pydantic验证库
FastAPI框架
JSON序列化
日志记录
路由模块
模式定义
服务实现
日志记录
时间线项
字幕信息
文本样式
数据流依赖
字幕信息生成的数据流遵循严格的依赖顺序：
- 输入验证：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确保数据完整性
- 智能参数修剪：自动处理长度不匹配问题，提供优雅降级
- 详细的日志记录：记录处理过程和警告信息
- 高性能处理：线性时间复杂度，适合大批量处理
- 扩展性强：模块化设计便于功能扩展
应用场景
- 视频字幕生成和编辑
- 多语言字幕处理
- 动态字幕效果制作
- 批量字幕信息管理
- 容错性要求较高的应用场景
未来改进方向
- 增加更多动画效果支持
- 优化性能以处理超大字幕集
- 提供更丰富的样式定制选项
- 增强国际化和本地化支持
- 扩展智能修剪功能，支持更多类型的参数验证
附录
使用示例
基本字幕生成
json
{
"texts": ["欢迎使用字幕功能", "这是第二个字幕"],
"timelines": [
{"start": 0, "end": 284891428},
{"start": 284891428, "end": 579578774}
]
}带样式的字幕生成
json
{
"texts": ["关键词高亮示例"],
"timelines": [{"start": 0, "end": 1000000}],
"font_size": 15,
"keyword_color": "#ff0000",
"keyword_font_size": 15,
"keywords": ["关键词"],
"in_animation": "展开",
"out_animation": "闪现"
}智能参数修剪示例
json
{
"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保持一致性 - 直观的导航：提供清晰的中英文版本链接
- 良好的可访问性：确保用户能够轻松找到目标语言版本
- 一致的用户体验：与其他文档保持相同的语言切换模式
这种设计提升了文档的可用性和国际化支持，让用户能够更方便地访问不同语言版本的文档内容。
附录
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate