mixvideo-v2/openapi.md

# Text Video Agent API 文档

## 概述

Text Video Agent API 是一个综合性的文本生成视频API服务，版本 1.0.6。该API提供了多种AI生成服务，包括图片生成、视频生成、音频生成、口型合成、数字人生成、LLM推理等功能，支持多个AI服务提供商。

## API 分类概览

### 1. 文件操作 (File Operations)
- 文件上传到云存储（COS/S3）
- 健康检测

### 2. 视频模板管理 (Video Template Management)
- 模板CRUD操作
- 任务类型检查
- 分页查询

### 3. 极梦视频生成 (JiMeng Video Generation)
- 视频生成（同步/异步）
- 任务状态查询

### 4. 任务管理 (Task Management)
- 异步任务提交
- 任务状态查询
- 模板化任务处理

### 5. 302AI Midjourney图片生成 (302AI Midjourney Image Generation)
- 图片生成（同步/异步）
- 图片描述反推
- 任务取消

### 6. 302AI 极梦视频生成 (302AI JiMeng Video Generation)
- 视频生成（同步/异步）
- 任务状态查询

### 7. 302AI Midjourney视频生成 (302AI Midjourney Video Generation)
- 视频生成服务
- 任务状态查询

### 8. 302AI VEO视频生成 (302AI VEO Video Generation)
- VEO视频生成
- 任务状态查询

### 9. Hedra口型合成 3.0 (Hedra Lip Sync 3.0)
- 口型合成任务
- 文件上传管理

### 10. 海螺API (HaiLuo API)
- 语音合成
- 声音克隆

### 11. ComfyUI工作流 (ComfyUI Workflow)
- 工作流执行
- 节点管理

### 12. 302AI聚合接口 (302AI Union APIs)
- 统一的图片/视频生成接口
- 支持多模型选择

### 13. 🔥稳定图片视频生成接口 (Stable Generation APIs)
- 图片生成任务提交
- 视频生成任务提交
- 任务状态查询

### 14. 🔥特殊模型接口 (Special Model APIs)
- Higgsfield Soul模型
- 首尾帧视频生成

### 15. 火山OmniHuman接口 (Volcano OmniHuman APIs)
- 图片人脸检测
- 视频生成

### 16. 火山数字人接口 (Volcano Digital Human APIs)
- 数字人创建
- 视频生成

### 17. LLM调用 (LLM APIs)
- 多模型推理
- Google Gemini多模态分析
- 文件上传到Google存储

### 18. 提示词预处理 (Prompt Processing) [已弃用]
- 获取示例提示词
- 健康检测

---

## 详细接口分析

### 1. 文件操作模块

#### 1.1 上传文件到COS (已弃用)
**接口**: `POST /api/file/upload`

**参数**:
- `file`: 要上传的文件

**作用**: 上传文件到腾讯云COS存储
**状态**: 已弃用，建议使用S3上传接口

#### 1.2 上传文件到S3 (推荐)
**接口**: `POST /api/file/upload/s3`

**参数**:
- `file`: 要上传的文件

**作用**: 上传文件到S3存储，支持CDN加速，性能更好

**返回**: FileUploadResponse
- `status`: 上传状态
- `msg`: 响应消息
- `data`: 文件URL

#### 1.3 健康检测
**接口**: `GET /api/file/health`

**作用**: 检查文件操作服务的健康状态

---

### 2. 视频模板管理模块

#### 2.1 获取视频模板列表
**接口**: `GET /api/template/default`

**参数**:
- `task_type` (可选): 任务类型筛选
- `page` (可选): 页码，从1开始，默认1
- `page_size` (可选): 每页记录数，默认100，最大1000
- `category` (可选): 模版分类标签，默认"全部"

**作用**: 获取视频模板列表，支持分页和按任务类型筛选

**返回**:
```json
{
  "status": true,
  "data": [模板数据列表],
  "page": 当前页码,
  "page_size": 每页数量,
  "total": 总记录数,
  "total_pages": 总页数
}
```

#### 2.2 检查任务类型可用性
**接口**: `GET /api/template/check/task_type`

**参数**:
- `task_type`: 要检查的任务类型

**作用**: 检查指定的任务类型是否可用（未被占用）

#### 2.3 创建视频模板
**接口**: `POST /api/template/create`

**参数**: 模板数据对象，必须包含task_type字段且唯一

**示例数据**:
```json
{
  "prompt": "Cozy, earthy-style visual...",
  "cover_url": "https://...",
  "video_url": "https://...",
  "description": "茶艺展示",
  "detailDescription": "茶艺仪式与草本排毒茶的自然精华展示",
  "title_zh": "养生草本茶艺展示",
  "aspect_ratio": "9:16",
  "engine": "mj",
  "presetPrompts": "11111\n22222",
  "task_type": "tea"
}
```

#### 2.4 更新视频模板
**接口**: `PUT /api/template/update`

**参数**: 模板数据对象，必须包含id字段

#### 2.5 删除视频模板
**接口**: `DELETE /api/template/delete/{template_id}`

**参数**:
- `template_id`: 要删除的模板ID

**作用**: 软删除视频模板

---

### 3. 极梦视频生成模块

#### 3.1 生成视频 (基础版)
**接口**: `POST /api/jm/generate-video`

**参数**:
- `prompt`: 视频生成提示词
- `img_url`: 图片URL地址
- `duration` (可选): 视频时长(秒)，默认5
- `max_wait_time` (可选): 最大等待时间，默认300秒
- `poll_interval` (可选): 轮询间隔，默认5秒
- `model_type` (可选): 模型类型，支持lite/pro，默认lite

#### 3.2 同步生成视频v2
**接口**: `POST /api/jm/sync/generate/video`

**参数**:
- `prompt`: 视频生成提示词
- `img_file`: 上传的图片文件
- `duration` (可选): 视频时长(秒)，默认5
- `max_wait_time` (可选): 最大等待时间，默认300秒
- `poll_interval` (可选): 轮询间隔，默认5秒
- `model_type` (可选): 模型类型，默认lite

**作用**: 支持通过图片文件生成视频，同步返回结果

#### 3.3 异步生成视频
**接口**: `POST /api/jm/async/generate/video`

**参数**:
- `prompt`: 视频生成提示词
- `img_url` (可选): 图片URL地址
- `img_file` (可选): 上传的图片文件
- `duration` (可选): 视频时长(秒)，默认5
- `model_type` (可选): 模型类型，默认lite

**作用**: 异步提交视频生成任务

#### 3.4 异步查询视频状态
**接口**: `GET /api/jm/async/query/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询异步视频生成任务的状态和结果

#### 3.5 健康检查
**接口**: `GET /api/jm/health`

**作用**: 检查极梦视频生成服务的健康状态

---

### 4. 任务管理模块

#### 4.1 新版异步提交任务
**接口**: `POST /api/task/create/task`

**参数**: TaskRequest对象
- `task_type` (可选): 任务类型 (tea/chop/lady/vlog)
- `prompt`: 生成提示词
- `img_url` (可选): 参考图片URL
- `ar` (可选): 生成图片的长宽比，默认9:16

**作用**: 异步提交任务到Modal进行处理，立即返回任务ID

#### 4.2 新版本异步提交任务v2
**接口**: `POST /api/task/create/task/v2`

**参数**: 同上

**作用**: 任务管理的升级版本

#### 4.3 异步查询任务状态
**接口**: `GET /api/task/status/{task_id}`

**参数**:
- `task_id`: 任务ID

**作用**: 查询任务执行状态和结果

#### 4.4 健康检测
**接口**: `GET /api/task/health`

**作用**: 检查任务管理服务的健康状态

---

### 5. 302AI Midjourney图片生成模块

#### 5.1 异步提交生图任务
**接口**: `POST /api/302/mj/async/generate/image`

**参数**:
- `prompt`: 图片生成提示词
- `img_file` (可选): 样貌参考图片

**作用**: 异步提交图片生成任务，立即返回任务ID

#### 5.2 取消任务
**接口**: `POST /api/302/mj/task/cancel`

**参数**:
- `task_id`: 要取消的任务ID

**作用**: 取消正在执行的图片生成任务

#### 5.3 异步查询任务状态
**接口**: `GET /api/302/mj/async/query/status`

**参数**:
- `task_id`: 任务ID
- `task_type` (可选): 任务类型，image(生图)/describe(反推提示词)，默认image
- `cdn_flag` (可选): 是否CDN转换，默认false（CDN转换耗时）
- `mode` (可选): 模式，默认fast

**作用**: 查询异步图片生成任务的状态和结果

#### 5.4 获取图像描述
**接口**: `POST /api/302/mj/sync/img/describe`

**参数**:
- `image_url`: 图片URL地址
- `max_wait_time` (可选): 最大等待时间，默认120秒
- `poll_interval` (可选): 轮询间隔，默认2秒

**作用**: 根据图片URL反推生成该图片的提示词

#### 5.5 通过文件获取生图提示词
**接口**: `POST /api/302/mj/sync/file/img/describe`

**参数**:
- `img_file`: 上传的图片文件

**作用**: 通过上传图片文件反推生成提示词

#### 5.6 同步生成图片
**接口**: `POST /api/302/mj/sync/image`

**参数**:
- `prompt`: 图片生成提示词
- `img_file` (可选): 样貌参考图片
- `max_wait_time` (可选): 最大等待时间，默认500秒
- `poll_interval` (可选): 轮询间隔，默认4秒
- `mode` (可选): 模式，支持fast/turbo，默认fast

**作用**: 同步生成图片，等待结果返回

---

### 6. 302AI 极梦视频生成模块

#### 6.1 同步生成视频v2
**接口**: `POST /api/302/jm/sync/generate/video`

**参数**:
- `prompt`: 视频生成提示词
- `img_file`: 生成视频的图片文件
- `duration` (可选): 视频时长(秒)，默认5
- `max_wait_time` (可选): 最大等待时间，默认300秒
- `poll_interval` (可选): 轮询间隔，默认5秒
- `model_type` (可选): 模型类型，默认lite

**作用**: 同步生成视频，等待结果返回

#### 6.2 异步生成视频
**接口**: `POST /api/302/jm/async/generate/video`

**参数**:
- `prompt`: 视频生成提示词
- `img_url` (可选): 图片URL地址
- `img_file` (可选): 上传的图片文件
- `duration` (可选): 视频时长(秒)，默认5
- `model_type` (可选): 模型类型，默认lite

**作用**: 异步提交视频生成任务

#### 6.3 异步查询视频状态
**接口**: `GET /api/302/jm/async/query/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询异步视频生成任务的状态和结果

---

### 7. 302AI Midjourney视频生成模块

#### 7.1 异步提交生成视频任务
**接口**: `POST /api/302/mj/video/async/submit`

**参数**:
- `prompt`: 生成视频的提示词
- `img_file` (可选): 首帧参考图文件

**作用**: 异步提交Midjourney视频生成任务

#### 7.2 异步查询生成任务进度
**接口**: `POST /api/302/mj/video/async/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询Midjourney视频生成任务的进度和结果

#### 7.3 同步生成视频
**接口**: `POST /api/302/mj/video/sync/generate/video`

**参数**:
- `prompt`: 生成视频的提示词
- `img_file`: 首帧参考图文件
- `timeout` (可选): 超时时间，默认300秒
- `interval` (可选): 轮询间隔，默认3秒

**作用**: 同步生成Midjourney视频，等待结果返回

---

### 8. 302AI VEO视频生成模块

#### 8.1 异步提交任务
**接口**: `POST /api/302/veo/video/async/submit`

**参数**:
- `prompt`: 生成视频的提示词
- `img_file` (可选): 首帧参考图

**作用**: 异步提交VEO视频生成任务

#### 8.2 同步生成视频
**接口**: `POST /api/302/veo/video/sync/generate/video`

**参数**:
- `prompt`: 生成视频的提示词
- `img_file` (可选): 首帧参考图
- `max_wait_time` (可选): 最大等待时间，默认500秒
- `interval` (可选): 轮询间隔，默认5秒

**作用**: 同步生成VEO视频，等待结果返回

#### 8.3 获取任务状态
**接口**: `GET /api/302/veo/video/task/{task_id}`

**参数**:
- `task_id`: 任务ID
- `img_mode` (可选): 图文到视频模式，默认false

**作用**: 查询VEO视频生成任务的状态和结果

---

### 9. Hedra口型合成 3.0 模块

#### 9.1 上传文件到Hedra平台
**接口**: `POST /api/302/hedra/v3/file/upload`

**参数**:
- `local_file`: 待上传的文件，支持音频、图片、视频、语音
- `purpose` (可选): 上传文件的用途，支持"image"、"audio"、"video"、"voice"，默认"image"

**作用**: 上传文件到Hedra平台，返回资源的ID

#### 9.2 异步提交任务
**接口**: `POST /api/302/hedra/v3/submit/task`

**参数**:
- `img_file`: 图片文件
- `audio_file`: 音频文件

**作用**: 异步提交口型合成任务

#### 9.3 查询任务状态
**接口**: `GET /api/302/hedra/v3/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询口型合成任务的执行状态和结果

---

### 10. 海螺API模块

#### 10.1 同步生成音频
**接口**: `POST /api/302/hl_router/sync/generate/speech`

**参数**:
- `text`: TTS文本内容
- `voice_id`: Voice ID
- `speed` (可选): 语速 [0.5, 2]，默认1.0
- `vol` (可选): 音量 (0,10]，默认1.0
- `emotion` (可选): 情感 ["happy", "sad", "angry", "fearful", "disgusted", "surprised", "calm"]

**作用**: 使用指定音色和参数生成语音

#### 10.2 查询克隆的音色ID
**接口**: `GET /api/302/hl_router/sync/get/voices`

**作用**: 查询可用的克隆音色ID列表，接口来自官方，302没有对应的中转接口

#### 10.3 上传素材到302ai
**接口**: `POST /api/302/hl_router/sync/file/upload`

**参数**:
- `audio_file`: 音频文件
- `purpose` (可选): 意图，默认voice_clone

**作用**: 上传音频文件用于声音复刻

#### 10.4 声音克隆
**接口**: `POST /api/302/hl_router/sync/voice/clone`

**参数**:
- `text`: 复刻的文本
- `model` (可选): 支持的模型，默认speech-02-hd
  - 可选: speech-02-hd, speech-02-turbo, speech-01-hd, speech-01-turbo
- `need_noise_reduction` (可选): 是否开启降噪，默认true
- `voice_id` (可选): 音色克隆voice_id
- `prefix` (可选): 音色voice_id前缀，默认BoWong-
- `audio_file` (可选): 参考音频文件

**作用**: 基于参考音频创建个性化音色

---

### 11. ComfyUI工作流模块

#### 11.1 获取运行节点
**接口**: `GET /api/comfy/fetch/running/node`

**参数**:
- `task_count` (可选): 运行任务的数目，默认1

**作用**: 根据任务数获取可用的运行节点

#### 11.2 异步提交任务
**接口**: `POST /api/comfy/async/submit/task`

**参数**:
- `prompt`: 工作流节点数据

**作用**: 异步提交ComfyUI工作流任务

#### 11.3 查询任务状态
**接口**: `GET /api/comfy/async/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询ComfyUI工作流任务的执行状态

#### 11.4 同步执行工作流
**接口**: `POST /api/comfy/sync/execute/workflow`

**参数**:
- `prompt`: 工作流JSON字符串

**作用**: 同步执行ComfyUI工作流，等待结果返回

---

### 12. 302AI聚合接口模块

#### 12.1 图片生成聚合接口

##### 获取支持的模型列表
**接口**: `GET /api/union/img/model/list`

**作用**: 获取所有支持的图片生成模型列表

##### 生图
**接口**: `POST /api/union/img/sync/generate/image`

**参数**:
- `model` (可选): 生图模型，默认midjourney-v7-t2i
- `prompt`: 生图提示词
- `img_file`: 参考图
- `aspect_ratio` (可选): 图片尺寸，默认9:16

**作用**: 统一的图片生成接口，支持多种模型
**参考文档**: https://doc.302.ai/286288228e0

#### 12.2 视频生成聚合接口

##### 获取支持的模型列表
**接口**: `GET /api/union/video/model/list`

**作用**: 获取所有支持的视频生成模型列表

##### 异步提交任务
**接口**: `POST /api/union/video/async/generate/video`

**参数**:
- `prompt`: 生图提示词
- `img_file`: 首帧图片
- `model` (可选): 生图模型，默认seedance_i2v
- `duration` (可选): 视频时长，默认5

##### 异步查询任务状态
**接口**: `GET /api/union/video/async/{task_id}/status`

**参数**:
- `task_id`: 任务ID

---

### 13. 🔥稳定图片视频生成接口模块

#### 13.1 获取支持的模型列表
**接口**: `GET /api/custom/model/list`

**参数**:
- `category` (可选): 分类，可取值: image, video，默认image

**作用**: 获取支持的图片或视频生成模型列表

#### 13.2 提交图片生成任务
**接口**: `POST /api/custom/image/submit/task`

**参数**: 通过multipart/form-data提交
- 支持多种图片生成模型
- 支持参考图片上传

**作用**: 提交图片生成任务，返回任务ID

#### 13.3 提交视频生成任务
**接口**: `POST /api/custom/video/submit/task`

**参数**: 通过multipart/form-data提交
- 支持多种视频生成模型
- 支持参考图片上传

**作用**: 提交视频生成任务，返回任务ID

#### 13.4 查询任务状态
**接口**: `GET /api/custom/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询图片或视频生成任务的状态和结果

---

### 14. 🔥特殊模型接口模块

#### 14.1 获取支持的模型列表
**接口**: `GET /api/custom/extend/model/list`

**作用**: 获取特殊模型的支持列表

#### 14.2 Higgsfield Soul模型

##### 创建角色
**接口**: `POST /api/custom/extend/higgsfield/create/character`

**参数**: 通过application/x-www-form-urlencoded提交

**作用**: 提交创建生成角色任务

##### 查询创建角色状态
**接口**: `POST /api/custom/extend/higgsfield/character/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询创建角色任务的状态

##### 提交生图任务
**接口**: `POST /api/custom/extend/higgsfield/submit/task`

**参数**: 通过application/x-www-form-urlencoded提交

**作用**: 使用Higgsfield Soul模型进行文生图

##### 查询任务状态
**接口**: `GET /api/custom/extend/higgsfield/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询Higgsfield任务执行状态

#### 14.3 首尾帧视频生成

##### 提交任务
**接口**: `POST /api/custom/extend/frame/submit/task`

**参数**: 通过application/x-www-form-urlencoded提交

**作用**: 提交首尾帧生成视频任务

##### 查询任务状态
**接口**: `GET /api/custom/extend/frame/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询首尾帧任务状态
**说明**: 只要返回的status类型为bool代表任务已经结束，直接从data里取值即可

---

### 15. 火山OmniHuman接口模块

#### 15.1 图片检测
**接口**: `POST /api/ark/omnihuman/img/recognition`

**参数**: 通过multipart/form-data提交图片文件

**作用**: 提交图片检测任务，检测图片中是否包含人、类人、拟人等主体

#### 15.2 视频生成
**接口**: `POST /api/ark/omnihuman/video/submit/task`

**参数**:
- `img_input`: 输入的图片，支持链接+文件流
- `audio_input`: 输入的音频，支持链接+文件流

**作用**: 提交视频生成任务
**返回**: {"status": True, 'data': '任务id', 'msg': '信息'}

#### 15.3 查询任务状态
**接口**: `GET /api/ark/omnihuman/task/status`

**参数**:
- `task_id`: 任务ID
- `task_type` (可选): 任务类型，支持face_detect, video_generate，默认face_detect

**作用**: 查询图片检测或视频生成任务的状态

---

### 16. 火山数字人接口模块

#### 16.1 上传视频生成云ID
**接口**: `POST /api/ark/digital/url2vid`

**参数**: 通过multipart/form-data提交
- 仅支持mp4格式的视频
- 视频时长较长时，建议使用链接

**作用**: 异步上传视频生成视频云ID

#### 16.2 创建数字人
**接口**: `POST /api/ark/digital/create`

**参数**: 通过application/x-www-form-urlencoded提交

**作用**: 提交创建数字人任务

#### 16.3 生成数字人视频
**接口**: `POST /api/ark/digital/video/submit/task`

**参数**: 通过multipart/form-data提交

**作用**: 生成数字人视频

#### 16.4 查询任务状态
**接口**: `GET /api/ark/digital/task/status`

**参数**:
- `task_id`: 任务ID
- `task_type` (可选): 任务类型，支持upload, create_digital, video_generate，默认video_generate

**作用**: 查询不同类型任务的状态
- upload: 上传视频文件
- create_digital: 创建数字人
- video_generate: 视频生成

---

### 17. LLM调用模块

#### 17.1 获取支持的模型列表
**接口**: `GET /api/llm/model/list`

**作用**: 获取支持的LLM模型列表

#### 17.2 调用大模型进行推理
**接口**: `POST /api/llm/chat`

**参数**: 通过application/x-www-form-urlencoded提交
- 支持多种LLM模型
- 可配置温度、最大token等参数

**作用**: 调用大模型进行文本推理

#### 17.3 调用Google推理
**接口**: `POST /api/llm/google/chat`

**参数**: 通过application/x-www-form-urlencoded提交

**作用**: 专门调用Google Gemini模型进行推理

#### 17.4 Gemini多模态分析（同步）
**接口**: `POST /api/llm/google/sync/media/analysis`

**参数**: 通过application/x-www-form-urlencoded提交
- `text_prompt`: 分析提示词
- `media_uri`: 媒体文件URI

**作用**: 同步进行Gemini多模态分析，支持视频、音频、图片，适合小文件

#### 17.5 Gemini多模态分析（异步）
**接口**: `POST /api/llm/google/async/media/analysis`

**参数**: 通过application/x-www-form-urlencoded提交
- `text_prompt`: 分析提示词
- `media_uri`: 媒体文件URI

**作用**: 异步进行Gemini多模态分析，适合需要长时间的推理过程

#### 17.6 上传文件到Google存储
**接口**: `POST /api/llm/google/vertex-ai/upload`

**参数**: 通过multipart/form-data提交
- `local_file`: 本地文件，支持音频、视频、图片

**作用**: 上传文件到谷歌存储，用于Gemini视觉功能
**返回格式**:
```json
{
  "status": "状态信息, true 成功, false 失败",
  "data": "gs://fashion_image_block/gallery_v2/mp4/1f76996f-a13e-450e-8c86-029c398932c4.mp4",
  "msg": "",
  "extra": "原始信息"
}
```

#### 17.7 查询推理过程结果
**接口**: `GET /api/llm/task/status`

**参数**:
- `task_id`: 任务ID

**作用**: 查询LLM推理任务的状态和结果
**返回说明**: status值为字符串时标识任务运行状态，为布尔值时标识任务运行完毕

---

### 18. 提示词预处理模块 [已弃用]

#### 18.1 获取示例提示词 [已弃用]
**接口**: `GET /api/prompt/default`

**参数**:
- `task_type` (可选): 任务类型

**作用**: 获取示例提示词
**状态**: 已弃用

#### 18.2 健康检测
**接口**: `GET /api/prompt/health`

**作用**: 检查提示词预处理服务的健康状态



---

## 接口组合调用关系与应用场景

### 场景1: 稳定图片生成流程

1. **获取模型列表** → `GET /api/custom/model/list?category=image`
   - 获取支持的图片生成模型

2. **提交生成任务** → `POST /api/custom/image/submit/task`
   - 提交图片生成任务

3. **轮询任务状态** → `GET /api/custom/task/status`
   - 定期查询任务进度直到完成

4. **文件上传** → `POST /api/file/upload/s3`
   - 将生成的图片上传到云存储

### 场景2: 图片到视频的完整流程

1. **上传参考图片** → `POST /api/file/upload/s3`
   - 上传用户的参考图片

2. **提交视频生成任务** → `POST /api/custom/video/submit/task`
   - 使用图片和提示词生成视频

3. **查询任务状态** → `GET /api/custom/task/status`
   - 监控视频生成进度

4. **保存到模板** → `POST /api/template/create`
   - 将成功的配置保存为模板

### 场景3: 模板化批量生产

1. **获取模板列表** → `GET /api/template/default`
   - 获取可用的视频模板

2. **检查任务类型** → `GET /api/template/check/task_type`
   - 确认任务类型可用性

3. **批量任务提交** → `POST /api/task/create/task/v2`
   - 基于模板批量提交任务

4. **状态监控** → `GET /api/task/status/{task_id}`
   - 监控所有任务的执行状态

### 场景4: 多模型对比生成

1. **获取模型列表** → `GET /api/union/img/model/list`
   - 获取支持的图片生成模型

2. **并行提交任务** → `POST /api/union/img/sync/generate/image`
   - 使用不同模型生成同一提示词

3. **结果对比分析**
   - 比较不同模型的生成效果

### 场景5: 声音克隆与TTS

1. **上传音频素材** → `POST /api/302/hl_router/sync/file/upload`
   - 上传用于克隆的音频文件

2. **执行声音克隆** → `POST /api/302/hl_router/sync/voice/clone`
   - 创建个性化音色

3. **查询音色列表** → `GET /api/302/hl_router/sync/get/voices`
   - 获取可用的音色ID

4. **生成语音** → `POST /api/302/hl_router/sync/generate/speech`
   - 使用克隆的音色生成语音

### 场景6: 工作流自动化

1. **获取运行节点** → `GET /api/comfy/fetch/running/node`
   - 获取可用的ComfyUI节点

2. **提交工作流** → `POST /api/comfy/async/submit/task`
   - 提交复杂的AI处理工作流

3. **监控执行** → `GET /api/comfy/async/task/status`
   - 跟踪工作流执行状态

### 场景7: 图片反推与再生成

1. **上传图片** → `POST /api/302/mj/sync/file/img/describe`
   - 上传图片获取描述提示词

2. **重新生成** → `POST /api/302/mj/sync/image`
   - 基于提示词重新生成

### 场景8: 多平台视频生成对比

1. **准备素材** → `POST /api/file/upload/s3`
   - 上传参考图片

2. **并行生成**:
   - `POST /api/302/jm/sync/generate/video` (302AI 极梦)
   - `POST /api/302/mj/video/sync/generate/video` (302AI MJ)
   - `POST /api/302/veo/video/sync/generate/video` (302AI VEO)

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. **上传训练视频** → `POST /api/ark/digital/url2vid`
   - 上传mp4格式的训练视频

2. **创建数字人** → `POST /api/ark/digital/create`
   - 基于训练视频创建数字人模型

3. **查询创建状态** → `GET /api/ark/digital/task/status?task_type=create_digital`
   - 监控数字人创建进度

4. **生成数字人视频** → `POST /api/ark/digital/video/submit/task`
   - 使用创建的数字人生成视频

5. **查询生成状态** → `GET /api/ark/digital/task/status?task_type=video_generate`
   - 监控视频生成进度

### 场景11: LLM多模态分析

1. **上传媒体文件** → `POST /api/llm/google/vertex-ai/upload`
   - 上传图片、视频或音频到Google存储

2. **提交分析任务** → `POST /api/llm/google/async/media/analysis`
   - 使用Gemini进行多模态分析

3. **查询分析结果** → `GET /api/llm/task/status`
   - 获取分析结果

### 场景12: 特殊模型应用

1. **获取特殊模型列表** → `GET /api/custom/extend/model/list`
   - 查看可用的特殊模型

2. **Higgsfield角色创建** → `POST /api/custom/extend/higgsfield/create/character`
   - 创建专属角色

3. **角色生图** → `POST /api/custom/extend/higgsfield/submit/task`
   - 使用创建的角色生成图片

4. **首尾帧视频** → `POST /api/custom/extend/frame/submit/task`
   - 基于首尾帧生成视频

### 场景13: 火山引擎OmniHuman应用

1. **图片人脸检测** → `POST /api/ark/omnihuman/img/recognition`
   - 检测图片中的人脸信息

2. **查询检测结果** → `GET /api/ark/omnihuman/task/status?task_type=face_detect`
   - 获取人脸检测结果

3. **提交视频生成** → `POST /api/ark/omnihuman/video/submit/task`
   - 基于图片和音频生成视频

4. **查询生成结果** → `GET /api/ark/omnihuman/task/status?task_type=video_generate`
   - 获取视频生成结果

---

## 数据结构说明

### 通用响应格式

#### FileUploadResponse
```json
{
  "status": boolean,     // 上传状态
  "msg": string,         // 响应消息
  "data": string|null    // 文件URL
}
```

#### TaskRequest
```json
{
  "task_type": string|null,  // 任务类型 (tea/chop/lady/vlog)
  "prompt": string,          // 生成提示词
  "img_url": string|null,    // 参考图片URL
  "ar": string              // 长宽比，默认9:16
}
```

#### VideoRequest
```json
{
  "prompt": string  // 视频生成提示词
}
```

### 错误响应格式

#### HTTPValidationError
```json
{
  "detail": [
    {
      "loc": [string|integer],  // 错误位置
      "msg": string,            // 错误消息
      "type": string           // 错误类型
    }
  ]
}
```

---

## 最佳实践建议

### 1. 错误处理
- 所有接口都返回422状态码表示验证错误
- 建议实现重试机制，特别是对于网络相关的操作
- 异步任务应该实现超时处理
- 对于长时间运行的任务，建议设置合理的轮询间隔

### 2. 性能优化
- **文件上传**: 优先使用S3上传接口而非COS接口，支持CDN加速
- **任务处理**: 对于大批量任务，使用异步接口避免阻塞
- **轮询策略**: 合理设置轮询间隔，避免过于频繁的状态查询
- **并发控制**: 控制并发任务数量，避免系统过载

### 3. 资源管理
- 及时清理不需要的任务和文件
- 使用取消接口停止不需要的任务 (`POST /api/302/mj/task/cancel`)
- 合理配置超时时间，避免资源浪费
- 实现任务队列管理，优化资源利用

### 4. 安全考虑
- **文件验证**: 验证上传文件的类型和大小，特别是音频、图片、视频文件
- **内容审核**: 对用户输入的提示词进行预审，防止生成不当内容
- **访问控制**: 实现适当的访问控制和频率限制
- **数据保护**: 保护用户上传的文件和生成的内容，特别是声音克隆等敏感数据
- **隐私保护**: 对于声音克隆和口型合成等涉及个人特征的功能，需要特别注意隐私保护

### 5. 用户体验
- **进度反馈**: 为长时间运行的任务提供进度反馈
- **队列管理**: 实现任务队列管理，避免用户等待
- **历史记录**: 提供任务历史记录和结果缓存
- **错误提示**: 提供友好的错误提示和解决建议

### 6. 开发建议
- **接口选择**: 根据需求选择同步或异步接口
- **模型选择**: 根据质量要求选择合适的模型 (lite/pro)
- **参数调优**: 合理设置等待时间和轮询间隔
- **监控告警**: 实现任务监控和异常告警机制

---

## 总结

Text Video Agent API 提供了一个完整的AI内容生成生态系统，支持从简单的图片生成到复杂的多模态内容创作、数字人生成、LLM推理等功能。通过合理的接口组合，可以实现丰富的应用场景，从个人创作工具到企业级内容生产平台。

### 核心优势

1. **多平台支持**: 集成了302AI、极梦、火山引擎、Hedra、海螺、Google Gemini等多个AI服务提供商
2. **功能完整**: 涵盖图片生成、视频生成、音频生成、口型合成、声音克隆、数字人生成、LLM推理、工作流处理等全链路功能
3. **灵活调用**: 提供同步和异步两种调用模式，满足不同性能需求
4. **模板化**: 支持视频模板管理，便于批量生产和标准化流程
5. **聚合接口**: 提供统一的接口访问多种模型，简化开发复杂度
6. **多模态融合**: 支持图片、视频、音频的综合处理和分析
7. **企业级功能**: 支持数字人创建、特殊模型应用、工作流自动化

### 技术特点

- **RESTful设计**: 遵循现代API设计原则，接口清晰易用
- **异步处理**: 支持长时间运行的AI任务异步处理
- **文件管理**: 完善的文件上传和存储解决方案，支持多种文件格式
- **错误处理**: 统一的错误响应格式和验证机制
- **扩展性**: 模块化设计，便于功能扩展和维护
- **版本管理**: 支持API版本迭代和功能升级
- **多媒体支持**: 全面支持图片、音频、视频等多种媒体格式
- **云原生**: 支持多种云存储和计算平台

### 新增功能亮点

1. **🔥稳定生成接口**: 提供更稳定可靠的图片和视频生成服务
2. **🔥特殊模型支持**: 集成Higgsfield Soul、首尾帧视频生成等特殊模型
3. **火山引擎集成**: 支持OmniHuman人脸检测和数字人生成
4. **LLM多模态分析**: 集成Google Gemini进行视频、音频、图片分析
5. **Hedra 3.0口型合成**: 提供最新版本的高质量口型同步功能
6. **海螺语音服务**: 集成专业的TTS和声音克隆功能
7. **302AI聚合服务**: 统一多个AI服务提供商的接口
8. **ComfyUI工作流**: 支持复杂的AI处理工作流

### 应用场景扩展

- **内容创作**: 图片生成、视频制作、音频合成
- **数字人应用**: 虚拟主播、客服机器人、教育培训
- **多媒体分析**: 视频内容理解、音频转录、图片识别
- **工作流自动化**: 批量处理、模板化生产
- **企业级应用**: 品牌营销、产品展示、培训材料

### 开发建议

建议开发者根据具体应用场景选择合适的接口组合，并实现完善的错误处理和用户反馈机制。特别注意：

1. **性能优化**: 合理使用同步/异步接口，避免长时间阻塞
2. **资源管理**: 及时清理临时文件和任务，控制并发数量
3. **隐私保护**: 在使用声音克隆、数字人生成等功能时注意隐私保护
4. **合规使用**: 确保生成内容符合相关法律法规要求
5. **监控告警**: 实现完善的任务监控和异常处理机制

## Rust SDK 生成指南

使用 OpenAPI Generator 可以快速生成 Rust SDK：

```bash
# 使用 Docker 生成 Rust SDK
docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \
  -i /local/openapi.json \
  -g rust \
  -o /local/text-video-agent-rust-sdk \
  --additional-properties=packageName=text_video_agent_client,packageVersion=1.0.6,supportAsync=true,library=reqwest

# 生成的 SDK 将包含：
# - 完整的 API 客户端代码
# - 类型定义和数据结构
# - 异步支持（基于 tokio）
# - 错误处理机制
# - 文档和示例
```

生成的 Rust SDK 将提供类型安全的 API 调用接口，支持异步操作，便于 Rust 开发者快速集成 Text Video Agent API 的各项功能。