Stooland Docs

Appearance

素材处理（Materials） ​

本页聚焦于 StoryBoardItem.vue 的素材选择与视频区域逻辑，包括素材匹配、视频预览/播放与删除的流程、时序图与接口字段说明。

流程概览 ​

  • 选择主题（topic）触发素材查询
  • 从素材池匹配/选择一个视频素材
  • 回填到分镜项：videoUrl/videoKey/thumbUrl
  • 支持预览、播放与删除

时序图（Sequence Diagram） ​

mermaid
sequenceDiagram
  participant U as User
  participant S as StoryBoardItem.vue
  participant M as MaterialDialog.vue
  participant API as image-api.js

  U->>S: 打开素材弹窗
  S->>M: 显示主题与素材列表
  M->>API: getRandomVideoByTopic(topicId)
  API-->>M: 返回视频素材（videoUrl, thumbUrl, key）
  M->>S: 确认选择素材
  S->>S: 设置 item.videoUrl / videoKey / thumbUrl
  S->>S: VideoArea.tryPlay() 自动播放
  opt 删除视频
    U->>S: 点击删除
    S->>S: onRemoveVideo 清理数据
  end

主要接口与字段说明 ​

  • getRandomVideoByTopic（image-api.js）

    • 描述：根据 topicId 返回一个视频素材
    • 请求字段：路径参数 id（主题ID）
    • 响应字段：
      • videoUrl：视频地址
      • thumbUrl：缩略图地址
      • key：OSS键名（存在时优先使用）
      • 其他素材属性（如 title、duration 等）

  • materialStoryboardItemSave / Update / Read（image-api.js）

    • 描述：分镜项的增删改查（API端）
    • 请求字段：title，description，line，videoUrl，audioUrl，videoKey 等
    • 响应字段：id，createdAt，updatedAt

示例 ​

拉取素材示例 ​

http
GET material/admin/image/getRandomVideoByTopic/{topicId}

返回：

json
{
  "videoUrl": "https://img.stooland.com/ai/data/image/2-153-14908.mp4?...",
  "thumbUrl": "https://img.stooland.com/...thumb.webp",
  "key": "ai/material/video/14908.mp4"
}

分镜项保存示例 ​

json
{
  "title": "未来城市空中交通",
  "description": "清晨的未来科技城市...",
  "line": "欢迎来到2150年的新都市...",
  "videoUrl": "https://img.stooland.com/.../14908.mp4",
  "videoKey": "ai/material/video/14908.mp4",
  "thumbUrl": "https://img.stooland.com/...thumb.webp"
}

注意事项 ​

  • 存在 videoKey 时优先使用 OSS 对象注册到ICE，避免长URL依赖与参数污染。
  • 选择素材后建议立即预览或播放，避免落地后才发现素材不合适。
  • 删除素材需同步清空 videoUrl/videoKey/thumbUrl 等字段。