特效信息生成接口
目录
简介
特效信息生成接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
Effect Infos 接口的依赖关系体现了清晰的分层架构设计：
graph TB
subgraph "外部依赖"
A[FastAPI]
B[Pydantic]
C[JSON]
D[Logging]
end
subgraph "内部模块"
E[router.v1]
F[schemas.effect_infos]
G[service.effect_infos]
H[middlewares.response]
I[utils.logger]
end
A --> E
B --> F
C --> G
D --> I
E --> F
E --> G
E --> H
F --> G
G --> I
H --> E
关键依赖关系
- 路由到服务层：路由器负责参数验证和调用服务层函数
- 数据模型依赖：服务层依赖数据模型进行参数验证
- 日志系统集成：服务层和路由器都集成了统一的日志系统
- 中间件处理：统一响应格式处理所有异常和成功响应
性能考虑
Effect Infos 接口在设计时充分考虑了性能优化：
时间复杂度分析
- 参数验证：O(n) - n 为特效数量
- 数据转换：O(n) - 遍历所有特效和时间线组合
- JSON 序列化：O(n) - 序列化结果数组
- 总体复杂度：O(n)
内存使用优化
- 流式处理：避免一次性加载大量数据
- 对象复用：重用中间结果减少内存分配
- 及时释放：处理完成后及时释放临时变量
并发处理
- 异步支持：基于 FastAPI 的异步特性
- 无状态设计：接口设计为无状态，便于水平扩展
- 连接池管理：合理管理数据库和外部服务连接
故障排除指南
常见问题诊断
1. 参数验证失败
症状：返回 422 状态码
原因：缺少必需参数或参数格式不正确
解决方法：
- 检查
effects和timelines参数是否存在 - 确认数组格式正确且包含有效数据
- 验证时间线对象包含
start和end字段
2. 数组长度不匹配
症状：返回 400 状态码，错误信息为 "Array length mismatch"
原因：effects 和 timelines 数组长度不一致
解决方法：
# 正确的做法
effects = ["blur", "vignette", "sepia"]
timelines = [
{
"start": 0, "end": 2000000},
{
"start": 2000000, "end": 4000000},
{
"start": 4000000, "end": 6000000}
]
3. 服务端错误
症状：返回 500 状态码
原因：服务层处理过程中发生异常
解决方法：
- 检查服务器日志获取详细错误信息
- 验证输入参数的有效性
- 确认系统资源充足
调试技巧
启用详细日志
# 在 main.py 中启用详细日志
uvicorn.run(app, host="0.0.0.0", port=30000, log_config=None, log_level="debug")
使用 curl 进行测试
curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/effect_infos" \
-H "Content-Type: application/json" \
-d '{
"effects": ["blur", "vignette"],
"timelines": [
{"start": 0, "end": 3000000},
{"start": 3000000, "end": 6000000}
]
}'
更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
