更新openapi.md

openapi.md

@@ -2,7 +2,7 @@
 
 ## 概述
 
-Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1.0.6。该API提供了多种AI生成服务，包括图片生成、视频生成、音频生成等功能，支持多个AI服务提供商。
+Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1.0.6。该API提供了多种AI生成服务，包括图片生成、视频生成、音频生成、口型合成等功能，支持多个AI服务提供商。
 
 ## API 分类概览
 
@@ -10,13 +10,14 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - 获取示例提示词
 - 健康检测
 
-### 2. 文件操作 (File Operations)  
-- 文件上传到云存储
+### 2. 文件操作 (File Operations)
+- 文件上传到云存储（COS/S3）
 - 健康检测
 
 ### 3. 视频模板管理 (Video Template Management)
 - 模板CRUD操作
 - 任务类型检查
+- 分页查询
 
 ### 4. Midjourney图片生成 (Midjourney Image Generation)
 - 图片生成（同步/异步）
@@ -30,31 +31,35 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 ### 6. 任务管理 (Task Management)
 - 异步任务提交
 - 任务状态查询
+- 模板化任务处理
 
-### 7. VEO视频生成 (VEO Video Generation)
-- 文本/图片到视频转换
-- 任务状态查询
-
-### 8. Midjourney视频生成 (Midjourney Video Generation)
+### 7. Midjourney视频生成 (Midjourney Video Generation)
 - 视频生成服务
 - 任务状态查询
 
-### 9. 302AI服务集成 (302AI Integration)
-- 多种AI服务的302AI版本
-- 图片生成、视频生成、音频生成
+### 8. 302AI服务集成 (302AI Integration)
+- Midjourney图片生成
+- 极梦视频生成
+- Midjourney视频生成
+- VEO视频生成
+- Hedra口型合成
 
-### 10. 聚合接口 (Union APIs)
+### 9. 聚合接口 (Union APIs)
 - 统一的图片/视频生成接口
 - 支持多模型选择
 
-### 11. ComfyUI工作流 (ComfyUI Workflow)
+### 10. ComfyUI工作流 (ComfyUI Workflow)
 - 工作流执行
 - 节点管理
 
-### 12. 海螺API (HaiLuo API)
+### 11. 海螺API (HaiLuo API)
 - 语音合成
 - 声音克隆
 
+### 12. Hedra口型合成 (Hedra Lip Sync)
+- 口型合成任务
+- 文件上传管理
+
 ---
 
 ## 详细接口分析
@@ -113,6 +118,7 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - `task_type` (可选): 任务类型筛选
 - `page` (可选): 页码，从1开始，默认1
 - `page_size` (可选): 每页记录数，默认100，最大1000
+- `category` (可选): 模版分类标签，默认"全部"
 
 **作用**: 获取视频模板列表，支持分页和按任务类型筛选
 
@@ -351,6 +357,65 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 
 ---
 
+### 8. Hedra口型合成模块
+
+#### 8.1 Hedra 2.0 版本
+
+##### 提交口型合成任务
+**接口**: `POST /api/302/hedra/v2/submit/task`
+
+**参数**:
+- `img_file`: 图片文件
+- `audio_file`: 音频文件
+
+**作用**: 提交口型合成任务，将音频与图片进行口型同步
+
+##### 查询任务状态 (已弃用)
+**接口**: `GET /api/302/hedra/v2/task/status`
+
+**参数**:
+- `task_id`: 任务ID
+
+**状态**: 已弃用
+
+##### 上传文件到Hedra服务器
+**接口**: `POST /api/302/hedra/v2/upload`
+
+**参数**:
+- `local_file`: 待上传的文件，支持图片和音频
+
+**作用**: 上传文件到Hedra服务器，仅支持image和audio格式
+
+#### 8.2 Hedra 3.0 版本
+
+##### 上传文件到Hedra平台
+**接口**: `POST /api/302/hedra/v3/file/upload`
+
+**参数**:
+- `local_file`: 待上传的文件，支持音频、图片、视频、语音
+- `purpose` (可选): 上传文件的用途，支持"image"、"audio"、"video"、"voice"，默认"image"
+
+**作用**: 上传文件到Hedra平台，返回资源的ID
+
+##### 异步提交任务
+**接口**: `POST /api/302/hedra/v3/submit/task`
+
+**参数**:
+- `img_file`: 图片文件
+- `audio_file`: 音频文件
+
+**作用**: 异步提交口型合成任务
+
+##### 查询任务状态
+**接口**: `GET /api/302/hedra/v3/task/status`
+
+**参数**:
+- `task_id`: 任务ID
+
+**作用**: 查询口型合成任务的执行状态和结果
+
+---
+
 ### 9. 302AI服务集成模块
 
 #### 9.1 302AI Midjourney图片生成
@@ -374,6 +439,7 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 **参数**:
 - `task_id`: 任务ID
 - `task_type` (可选): 任务类型，image(生图)/describe(反推提示词)，默认image
+- `cdn_flag` (可选): 是否CDN转换，默认false（CDN转换耗时）
 
 ##### 获取图像描述
 **接口**: `POST /api/302/mj/sync/img/describe`
@@ -460,6 +526,8 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - `prompt`: 生成视频的提示词
 - `img_file` (可选): 首帧参考图
 
+**作用**: 异步提交VEO视频生成任务
+
 ##### 同步生成视频
 **接口**: `POST /api/302/veo/video/sync/generate/video`
 
@@ -469,6 +537,8 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - `max_wait_time` (可选): 最大等待时间，默认500秒
 - `interval` (可选): 轮询间隔，默认5秒
 
+**作用**: 同步生成VEO视频，等待结果返回
+
 ##### 获取任务状态
 **接口**: `GET /api/302/veo/video/task/{task_id}`
 
@@ -476,11 +546,13 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - `task_id`: 任务ID
 - `img_mode` (可选): 图文到视频模式，默认false
 
+**作用**: 查询VEO视频生成任务的状态和结果
+
 ---
 
-### 10. 海螺API模块
+### 11. 海螺API模块
 
-#### 10.1 同步生成音频
+#### 11.1 同步生成音频
 **接口**: `POST /api/302/hl_router/sync/generate/speech`
 
 **参数**:
@@ -492,12 +564,12 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 
 **作用**: 使用指定音色和参数生成语音
 
-#### 10.2 查询克隆的音色ID
+#### 11.2 查询克隆的音色ID
 **接口**: `GET /api/302/hl_router/sync/get/voices`
 
 **作用**: 查询可用的克隆音色ID列表，接口来自官方，302没有对应的中转接口
 
-#### 10.3 上传素材到302ai
+#### 11.3 上传素材到302ai
 **接口**: `POST /api/302/hl_router/sync/file/upload`
 
 **参数**:
@@ -506,7 +578,7 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 
 **作用**: 上传音频文件用于声音复刻
 
-#### 10.4 声音克隆
+#### 11.4 声音克隆
 **接口**: `POST /api/302/hl_router/sync/voice/clone`
 
 **参数**:
@@ -522,9 +594,9 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 
 ---
 
-### 11. 聚合接口模块
+### 10. 聚合接口模块
 
-#### 11.1 图片生成聚合接口
+#### 10.1 图片生成聚合接口
 
 ##### 获取支持的模型列表
 **接口**: `GET /api/union/img/model/list`
@@ -543,7 +615,7 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 **作用**: 统一的图片生成接口，支持多种模型
 **参考文档**: https://doc.302.ai/286288228e0
 
-#### 11.2 视频生成聚合接口
+#### 10.2 视频生成聚合接口
 
 ##### 获取支持的模型列表
 **接口**: `GET /api/union/video/model/list`
@@ -707,6 +779,37 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 3. **效果对比**
    - 比较不同平台的生成效果和速度
 
+### 场景9: 口型合成与语音生成
+
+1. **上传素材** → `POST /api/302/hedra/v3/file/upload`
+   - 上传人物图片和音频文件
+
+2. **声音克隆** → `POST /api/302/hl_router/sync/voice/clone`
+   - 基于音频文件创建个性化音色
+
+3. **生成语音** → `POST /api/302/hl_router/sync/generate/speech`
+   - 使用克隆的音色生成新的语音
+
+4. **口型合成** → `POST /api/302/hedra/v3/submit/task`
+   - 将生成的语音与人物图片进行口型同步
+
+5. **查询结果** → `GET /api/302/hedra/v3/task/status`
+   - 获取最终的口型合成视频
+
+### 场景10: 聚合接口多模型测试
+
+1. **获取模型列表** → `GET /api/union/img/model/list`
+   - 查看支持的图片生成模型
+
+2. **批量测试** → `POST /api/union/img/sync/generate/image`
+   - 使用不同模型生成同一提示词
+
+3. **视频模型测试** → `GET /api/union/video/model/list`
+   - 获取视频生成模型列表
+
+4. **视频生成对比** → `POST /api/union/video/async/generate/video`
+   - 使用不同视频模型进行对比测试
+
 ---
 
 ## 数据结构说明
@@ -777,10 +880,11 @@ Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1
 - 实现任务队列管理，优化资源利用
 
 ### 4. 安全考虑
-- **文件验证**: 验证上传文件的类型和大小
-- **内容审核**: 对用户输入的提示词进行预审
+- **文件验证**: 验证上传文件的类型和大小，特别是音频、图片、视频文件
+- **内容审核**: 对用户输入的提示词进行预审，防止生成不当内容
 - **访问控制**: 实现适当的访问控制和频率限制
-- **数据保护**: 保护用户上传的文件和生成的内容
+- **数据保护**: 保护用户上传的文件和生成的内容，特别是声音克隆等敏感数据
+- **隐私保护**: 对于声音克隆和口型合成等涉及个人特征的功能，需要特别注意隐私保护
 
 ### 5. 用户体验
 - **进度反馈**: 为长时间运行的任务提供进度反馈
@@ -802,44 +906,31 @@ Text Video Agent API 提供了一个完整的AI内容生成生态系统，支持
 
 ### 核心优势
 
-1. **多平台支持**: 集成了Midjourney、极梦、VEO、302AI等多个AI服务提供商
-2. **功能完整**: 涵盖图片生成、视频生成、音频生成、工作流处理等全链路功能
+1. **多平台支持**: 集成了Midjourney、极梦、VEO、302AI、Hedra、海螺等多个AI服务提供商
+2. **功能完整**: 涵盖图片生成、视频生成、音频生成、口型合成、声音克隆、工作流处理等全链路功能
 3. **灵活调用**: 提供同步和异步两种调用模式，满足不同性能需求
 4. **模板化**: 支持视频模板管理，便于批量生产和标准化流程
 5. **聚合接口**: 提供统一的接口访问多种模型，简化开发复杂度
+6. **多模态融合**: 支持图片、视频、音频的综合处理和口型合成
 
 ### 技术特点
 
 - **RESTful设计**: 遵循现代API设计原则，接口清晰易用
 - **异步处理**: 支持长时间运行的AI任务异步处理
-- **文件管理**: 完善的文件上传和存储解决方案
+- **文件管理**: 完善的文件上传和存储解决方案，支持多种文件格式
 - **错误处理**: 统一的错误响应格式和验证机制
 - **扩展性**: 模块化设计，便于功能扩展和维护
+- **版本管理**: 支持API版本迭代，如Hedra 2.0/3.0等
+- **多媒体支持**: 全面支持图片、音频、视频等多种媒体格式
 
-建议开发者根据具体应用场景选择合适的接口组合，并实现完善的错误处理和用户反馈机制，以提供最佳的用户体验。
+### 新增功能亮点
 
-### 8. Midjourney视频生成模块
+1. **Hedra口型合成**: 支持2.0和3.0版本，提供高质量的口型同步功能
+2. **海螺语音服务**: 集成专业的TTS和声音克隆功能
+3. **聚合接口**: 统一多个AI服务提供商的接口，简化集成复杂度
+4. **ComfyUI工作流**: 支持复杂的AI处理工作流
+5. **302AI全家桶**: 提供Midjourney、极梦、VEO等服务的302AI版本
 
-#### 8.1 异步提交生成视频任务
-**接口**: `POST /api/mj/video/async/submit`
+建议开发者根据具体应用场景选择合适的接口组合，并实现完善的错误处理和用户反馈机制，以提供最佳的用户体验。特别是在使用声音克隆和口型合成等功能时，需要注意隐私保护和合规使用。
 
-**参数**:
-- `prompt`: 生成视频的提示词
-- `img_url` (可选): 图片URL
-- `img_file` (可选): 图片文件
 
-#### 8.2 异步查询生成任务进度
-**接口**: `POST /api/mj/video/async/task/status`
-
-**参数**:
-- `task_id`: 任务ID
-
-#### 8.3 同步生成视频
-**接口**: `POST /api/mj/video/sync/gen`
-
-**参数**:
-- `prompt`: 生成视频的提示词
-- `img_url` (可选): 图片URL
-- `img_file` (可选): 图片文件
-
----