# Sora 自定义节点功能说明

## 已实现的功能

### ✅ 1. Text-to-Video（文本生成视频）
**节点名称**: `SoraTextToVideo`

从文本提示生成视频，支持完整的 Sora 参数配置。

**主要参数**:
- `prompt`: 视频描述文本
- `negative_prompt`: 负面提示
- `duration_seconds`: 视频时长
- `aspect_ratio`: 宽高比
- `fps`: 帧率
- `guidance_scale`: 引导强度
- `seed`: 随机种子

### ✅ 2. Image-to-Video（图像生成视频）
**节点名称**: `SoraImageToVideo`

从图像生成视频，完全支持 ComfyUI 的图像输入格式。

**支持的图像输入格式**:
- ✅ PIL Image 对象
- ✅ Numpy 数组（自动处理各种形状）
- ✅ 文件路径（PNG, JPG, WebP）
- ✅ Base64 编码字符串

**主要参数**:
- `image`: ComfyUI 图像输入（必需）
- `prompt`: 视频描述（必需）
- 其他参数与 Text-to-Video 相同

### ✅ 3. Video-to-Video（视频编辑/扩展）
**节点名称**: `SoraVideoToVideo`

对现有视频进行编辑、扩展或风格转换。

**支持的操作类型**:
- `extend`: 扩展视频时长
- `edit`: 根据提示编辑视频内容
- `inpaint`: 视频修复/填充
- `style_transfer`: 风格迁移

**主要参数**:
- `video`: 视频文件路径或 base64 字符串（必需）
- `prompt`: 编辑描述（必需）
- `operation`: 操作类型（extend/edit/inpaint/style_transfer）
- `extension_seconds`: 扩展时长（用于 extend 操作）
- 其他参数与其他节点相同

## 技术特性

### 🔧 文件上传支持
- 扩展了 `SoraClient` 以支持 `multipart/form-data` 上传
- 自动处理图像和视频文件的编码和上传
- 支持多种 MIME 类型

### 🖼️ 图像处理
- 自动格式转换（PIL ↔ Numpy ↔ 文件）
- 自动处理不同的数组形状（batch, channels-first, channels-last）
- 自动归一化（0-1 范围转换为 0-255）
- 自动颜色空间转换（RGBA → RGB）

### 📹 视频处理
- 支持多种视频格式（MP4, MOV, AVI, WebM）
- 支持文件路径和 base64 编码
- 自动 MIME 类型检测

### 🔄 轮询机制
- 所有节点都支持异步任务轮询
- 可配置的轮询间隔和超时时间
- 自动状态检测和错误处理

### 📥 下载支持
- 可选的视频下载功能
- 支持目录或文件路径
- 自动文件命名（使用 job_id）

## 使用示例

### Text-to-Video
```python
# 在 ComfyUI 中直接使用节点
# 输入: prompt = "A beautiful sunset over the ocean"
# 输出: job_id, status, result_json
```

### Image-to-Video
```python
# 连接 ComfyUI 的图像节点到 SoraImageToVideo
# 输入: image (来自 LoadImage 节点), prompt = "Animate this image"
# 输出: job_id, status, result_json
```

### Video-to-Video
```python
# 扩展视频
# 输入: video = "/path/to/video.mp4", operation = "extend", extension_seconds = 5.0
# 输出: job_id, status, result_json
```

## 兼容性

- ✅ 仅使用 Python 标准库（核心功能）
- ✅ 可选依赖：Pillow（PIL）和 numpy（用于更好的图像处理）
- ✅ 完全兼容 ComfyUI 的节点系统
- ✅ 支持所有 ComfyUI 图像格式

## API 兼容性

节点设计为与 Sora 兼容的 REST API 配合使用，支持：
- OpenAI Sora API（当可用时）
- 自定义 Sora 兼容后端
- 可配置的 base_url 和 endpoint

## 错误处理

- ✅ 清晰的错误消息
- ✅ API 错误自动捕获和报告
- ✅ 超时保护
- ✅ 输入验证

## 未来可能的扩展

- [ ] 批量处理支持
- [ ] 视频预览功能
- [ ] 更多视频操作类型
- [ ] 实时进度回调
- [ ] 视频质量/分辨率选项