提取帧节点

<title>提取帧节点</title>

> 本文档抓取自官方文档中心（2026-10-10 快照），具体功能以实际产品为准。

# 提取帧节点

## 概述

提取帧节点用于从视频中提取指定帧（首帧或尾帧）并创建图片节点。

## 功能特点

1. **支持首帧和尾帧提取**：可选择提取视频的第一帧或最后一帧
2. **自动创建图片节点**：提取成功后自动创建新的图片节点
3. **支持视频节点连接**：可连接视频节点，直接使用其视频URL
4. **避免重复下载**：连接的视频已在服务器时，直接使用本地路径，无需重新下载上传

## 使用方法

### 1. 创建节点

通过左侧菜单点击"提取帧"按钮创建节点。

### 2. 输入视频

有两种方式输入视频：

- **上传视频文件**：点击"视频"字段的上传按钮，选择本地视频文件
- **连接视频节点**：从视频节点的输出端口拖拽连接到提取帧节点的输入端口

### 3. 选择帧类型

在下拉菜单中选择：

- **首帧**：提取视频的第一帧
- **尾帧**：提取视频的最后一帧

### 4. 提取帧

点击"提取帧"按钮，系统会：

1. 提取指定帧
2. 创建新的图片节点
3. 自动建立连接线

## 节点数据

```javascript
{
  type: 'extract_frame',
  data: {
    videoFile: null,        // 上传的视频文件（不保存）
    videoUrl: '',           // 视频URL（服务器URL会保存）
    videoName: '',          // 视频名称
    frameType: 'first',     // 帧类型：'first' 或 'last'
    extractedImageNodeId: null,  // 提取后创建的图片节点ID
    status: 'idle'          // 状态：idle, extracting, success, error
  }
}
```

## 后端 API

### 提取帧接口

```
POST /api/video-workflow/extract-frame
```

参数：

- `file`：视频文件（可选，与 video_url 二选一）
- `video_url`：视频URL（可选，服务器上的视频路径）
- `frame_type`：帧类型，`first` 或 `last`（默认 `first`）

返回：

```json
{
  "code": 0,
  "data": {
    "url": "http://host/upload/temp/xxx/frame_xxx.jpg"
  }
}
```

### 视频URL优化

当 `video_url` 参数传入服务器上的视频路径时（如 `/upload/workflow/1/xxx.mp4`），后端会直接使用本地文件路径，避免重复下载。

## 连接类型

提取帧节点创建的图片连接使用特殊的 `portType: 'extracted'`：

- 源端口：提取帧节点的 output 端口
- 目标端口：图片节点的 input 端口

## 注意事项

1. **视频格式**：支持常见视频格式（MP4、MOV、AVI等）
2. **提取时长**：尾帧提取可能需要较长时间，取决于视频长度
3. **图片格式**：提取的帧保存为 JPG 格式
4. **工作流保存**：提取成功后会自动保存工作流

## 错误处理

| 错误 | 原因 | 解决方案 |
|-|-|-|
| 请先上传视频或连接视频节点 | 未提供视频 | 上传视频或连接视频节点 |
| 视频文件不存在 | video_url 指向的文件不存在 | 检查视频URL是否正确 |
| 提取失败 | FFmpeg处理错误 | 检查视频格式是否支持 |