媒体信息生成接口

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论

简介

本文件为媒体信息生成接口的完整 API 文档，覆盖以下六个核心接口：

• /v1/audio_infos：根据音频 URL 和时间线生成音频信息
• /v1/imgs_infos：根据图片 URL 和时间线生成图片信息
• /v1/video_infos：根据视频 URL 和时间线生成视频信息
• /v1/caption_infos：根据文本和时间线生成字幕信息
• /v1/effect_infos：根据特效名称和时间线生成特效信息
• /v1/keyframes_infos：根据关键帧类型、位置比例和值生成关键帧信息

文档详细说明各接口的请求参数、响应结构、生成规则与业务逻辑，并提供错误处理策略、性能建议与使用示例。

项目结构

该服务采用 FastAPI 路由器 + Pydantic 数据模型 + 业务服务层的三层架构：

• 路由层：定义 API 路径、请求/响应模型绑定与日志记录
• 数据模型层：定义请求与响应的数据结构
• 服务层：实现具体的媒体信息生成逻辑，输出 JSON 字符串

graph TB
Client["客户端"] --> Router["FastAPI 路由器<br/>/v1/*"]
Router --> Schemas["Pydantic 数据模型<br/>schemas/*_infos.py"]
Router --> Service["业务服务层<br/>service/*_infos.py"]
Service --> JSON["JSON 字符串响应"]

核心组件

• 路由器：在 /v1 下注册六个信息生成接口，负责参数校验、调用服务层并返回 JSON 字符串
• 数据模型：每个接口对应一组请求/响应模型，统一字段语义与约束
• 服务层：实现具体生成逻辑，确保输入长度一致性、参数可选性与 JSON 序列化

架构总览

六个接口共享相同的调用链：路由层接收请求 → 校验参数 → 调用服务层 → 返回 JSON 字符串。

sequenceDiagram
participant C as "客户端"
participant R as "路由层<br/>/v1/*"
participant S as "服务层<br/>service/*_infos.py"
participant J as "JSON 输出"
C->>R : 发送请求含参数
R->>R : 参数校验长度匹配等
R->>S : 调用对应服务函数
S->>S : 生成信息列表逐项构建
S->>J : 序列化为 JSON 字符串
R-->>C : 返回 JSON 字符串响应

详细组件分析

/v1/audio_infos 接口

• 功能：根据音频 URL 列表与时间线数组生成音频信息 JSON
• 请求参数
  • mp3_urls：音频文件 URL 数组
  • timelines：时间线数组，每项包含 start/end（微秒）
  • audio_effect：可选，音频效果名称
  • volume：可选，音量（浮点数）
• 响应结构：infos 为 JSON 字符串，包含每条音频的 url、起止时间及可选效果与音量
• 生成规则
  • 校验 mp3_urls 与 timelines 长度一致
  • 逐项构建对象：audio_url、start、end；若提供则附加 audio_effect、volume
  • 输出 JSON 字符串
• 错误处理：长度不匹配抛出异常
• 使用场景：批量导入音频并按时间线切分与配置音效/音量

flowchart TD
Start(["进入 /audio_infos"]) --> Validate["校验 mp3_urls 与 timelines 长度"]
Validate --> LengthOK{"长度一致？"}
LengthOK --> |否| RaiseErr["抛出异常"]
LengthOK --> |是| Build["遍历构建音频信息对象"]
Build --> Optional["追加可选参数效果/音量"]
Optional --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

/v1/imgs_infos 接口

• 功能：根据图片 URL 列表与时间线数组生成图片信息 JSON
• 请求参数
  • imgs：图片 URL 列表
  • timelines：时间线数组
  • width/height：可选，视频宽高
  • in_animation/out_animation/loop_animation：可选，入场/出场/循环动画名称，支持"|"分隔的多动画
  • in/out/loop_animation_duration：可选，对应动画时长
  • transition/transition_duration：可选，转场名称与时长
• 响应结构：infos 为 JSON 字符串，包含每张图片的 url、起止时间及可选尺寸与动画配置
• 生成规则
  • 校验 imgs 与 timelines 长度一致
  • 解析动画参数：将"|"分隔的字符串拆分为列表
  • 扩展逻辑：若动画数量少于片段数，使用最后一个动画补齐；多余时截断
  • 逐项构建对象：image_url、start、end；追加 width/height 与动画配置
• 错误处理：长度不匹配抛出异常
• 使用场景：批量图片按时间线展示，支持多动画与转场

flowchart TD
Start(["进入 /imgs_infos"]) --> ParseAnim["解析动画参数| 分隔"]
ParseAnim --> Validate["校验 imgs 与 timelines 长度"]
Validate --> LenOK{"长度一致？"}
LenOK --> |否| RaiseErr["抛出异常"]
LenOK --> |是| Extend["扩展动画：不足用最后一个，多余截断"]
Extend --> Build["逐项构建图片信息对象"]
Build --> Optional["追加可选参数尺寸/动画/转场"]
Optional --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

/v1/video_infos 接口

• 功能：根据视频 URL 列表与时间线数组生成视频信息 JSON
• 请求参数
  • video_urls：视频 URL 列表
  • timelines：时间线数组
  • width/height：可选，视频宽高
  • mask：可选，视频蒙版类型（如圆形、矩形等）
  • transition/transition_duration：可选，转场名称与时长
  • volume：可选，音量（默认 1.0）
• 响应结构：infos 为 JSON 字符串，包含每段视频的 url、start、end、duration 及可选参数
• 生成规则
  • 校验 video_urls 与 timelines 长度一致
  • 计算每段 duration = end - start
  • 逐项构建对象并追加可选参数
• 错误处理：长度不匹配抛出异常
• 使用场景：批量视频拼接，支持尺寸、蒙版、转场与音量控制

flowchart TD
Start(["进入 /video_infos"]) --> Validate["校验 video_urls 与 timelines 长度"]
Validate --> LenOK{"长度一致？"}
LenOK --> |否| RaiseErr["抛出异常"]
LenOK --> |是| Calc["计算每段 duration=end-start"]
Calc --> Build["逐项构建视频信息对象"]
Build --> Optional["追加可选参数尺寸/蒙版/转场/音量"]
Optional --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

/v1/caption_infos 接口

• 功能：根据文本列表与时间线数组生成字幕信息 JSON
• 请求参数
  • texts：文本列表
  • timelines：时间线数组
  • font_size：可选，字体大小
  • keyword_color/keyword_font_size：可选，关键词颜色与字号
  • keywords：可选，与文本一一对应的关键词列表
  • in_animation/out_animation/loop_animation：可选，入场/出场/循环动画名称
  • in/out/loop_animation_duration：可选，对应动画时长
  • transition/transition_duration：可选，转场名称与时长
• 响应结构：infos 为 JSON 字符串，包含每条字幕的 start、end、text 及可选样式与动画
• 生成规则
  • 校验 texts 与 timelines 长度一致
  • 逐项构建对象：start、end、text
  • 若提供 keywords，按索引分配关键词；不足则后续文本关键词为空字符串
  • 追加可选样式与动画参数
• 错误处理：长度不匹配抛出异常
• 使用场景：批量字幕生成，支持关键词高亮与多种动画

flowchart TD
Start(["进入 /caption_infos"]) --> Validate["校验 texts 与 timelines 长度"]
Validate --> LenOK{"长度一致？"}
LenOK --> |否| RaiseErr["抛出异常"]
LenOK --> |是| Build["逐项构建字幕信息对象"]
Build --> Keyword["分配关键词不足补空"]
Keyword --> Optional["追加可选样式与动画参数"]
Optional --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

/v1/effect_infos 接口

• 功能：根据特效名称列表与时间线数组生成特效信息 JSON
• 请求参数
  • effects：特效名称列表
  • timelines：时间线数组
• 响应结构：infos 为 JSON 字符串，包含每条特效的 effect_title、start、end
• 生成规则
  • 校验 effects 与 timelines 长度一致
  • 逐项构建对象：effect_title、start、end
• 错误处理：长度不匹配抛出异常
• 使用场景：批量应用特效到指定时间段

flowchart TD
Start(["进入 /effect_infos"]) --> Validate["校验 effects 与 timelines 长度"]
Validate --> LenOK{"长度一致？"}
LenOK --> |否| RaiseErr["抛出异常"]
LenOK --> |是| Build["逐项构建特效信息对象"]
Build --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

/v1/keyframes_infos 接口

• 功能：根据关键帧类型、位置比例与值生成关键帧信息 JSON
• 请求参数
  • ctype：关键帧类型（如位置 X/Y 等）
  • offsets：位置比例字符串，以"|"分隔（0-100）
  • values：对应值字符串，以"|"分隔
  • segment_infos：片段信息数组，包含 id/start/end
  • height/width：可选，用于坐标类关键帧的归一化
• 响应结构：keyframes_infos 为 JSON 字符串，包含每条关键帧的 offset（片段内相对时间）、property、segment_id、value
• 生成规则
  • 解析 offsets 与 values，校验长度一致
  • 遍历每个片段，计算相对时间偏移 = 百分比 × 片段时长
  • 根据 ctype 对值进行归一化（如 PositionX/PositionY 除以宽高）
  • 逐项构建关键帧对象
• 错误处理：offsets/values 长度不匹配或参数非法时抛出异常
• 使用场景：为视频片段设置位置、缩放等属性的关键帧动画

flowchart TD
Start(["进入 /keyframes_infos"]) --> Parse["解析 offsets 与 values| 分隔"]
Parse --> Validate["校验长度一致"]
Validate --> LenOK{"长度一致？"}
LenOK --> |否| RaiseErr["抛出异常"]
LenOK --> |是| LoopSeg["遍历每个片段id/start/end"]
LoopSeg --> CalcOffset["计算相对时间偏移百分比×时长"]
CalcOffset --> Normalize["按 ctype 归一化值如需"]
Normalize --> Build["构建关键帧对象offset/property/segment_id/value"]
Build --> Serialize["序列化为 JSON 字符串"]
Serialize --> End(["返回响应"])
RaiseErr --> End

依赖关系分析

六个接口均依赖于通用的时间线数据结构 TimelineItem（来自音频时间线模块）。路由层将请求参数转换为字典列表后传递给服务层，服务层负责参数校验与 JSON 序列化。

graph LR
Router["路由层<br/>/v1/*"] --> Schemas["数据模型<br/>*_infos.py"]
Router --> Service["服务层<br/>service/*_infos.py"]
Schemas --> Timeline["时间线模型<br/>TimelineItem"]
Service --> JSON["JSON 字符串"]

性能考虑

• 输入校验：所有接口在服务层进行长度一致性检查，避免无效数据进入后续流程
• 序列化开销：JSON 序列化为一次性操作，建议控制单次请求的片段数量，避免过大的 JSON 字符串
• 动画扩展逻辑：图片与字幕的动画参数支持"不足用最后一个"的扩展策略，减少前端复杂度
• 归一化处理：关键帧值按宽高归一化，降低前端坐标换算成本
• 日志记录：服务层记录处理进度与结果，便于监控与排障

故障排除指南

• 长度不匹配
  • 现象：抛出异常，提示某数组长度与 timelines 不一致
  • 处理：确保传入的 URL/文本/特效列表与 timelines 数量相同
• 关键帧参数解析失败
  • 现象：offsets/values 长度不一致导致异常
  • 处理：确认"|"分隔符使用正确，且数量一致
• 关键帧类型与值不匹配
  • 现象：归一化失败或值范围异常
  • 处理：确保 ctype 与 width/height 设置正确，值符合预期范围

结论

媒体信息生成接口通过统一的参数模型与服务层实现，提供了从音频、图片、视频、字幕、特效到关键帧的全链路信息生成能力。接口设计强调参数一致性、可选配置与 JSON 序列化输出，适合在批量处理与自动化脚本中使用。建议在生产环境中结合日志与监控，合理控制请求规模并确保输入参数的完整性与合法性。