overview.md - VideoClaw

overview.md

1	# Pipeline 总览
2
3	一次性 Pipeline 用于不需要六阶段人工停点的短流程任务。任务创建后在后台执行，前端通过 SSE 订阅进度，产物会实时登记到任务元数据中。
4
5	## 可用 Pipeline
6
7	\| Pipeline \| 前端名称 \| API \| 说明 \|
8	\|----------\|----------\|-----\|------\|
9	\| `standard` \| 文艺短视频 \| `/api/pipelines/standard/tasks` \| 输入创作灵感或完整文案，生成图片、TTS，并按「图片拼接 / 动态视频」模式合成成片 \|
10	\| `action_transfer` \| 动作迁移 \| `/api/pipelines/action_transfer/tasks` \| 输入角色图片、动作视频和提示词，调用动作迁移视频模型 \|
11	\| `digital_human` \| 数字人口播 \| `/api/pipelines/digital_human/tasks` \| 输入人物图片和口播文案，生成数字人口播视频 \|
12
13	## 任务元数据与产物目录
14
15	```text
16	video-claw/backend/code/data/tasks/{task_id}.json
17	video-claw/backend/code/result/task/{task_id}/
18	```
19
20	任务元数据包含：
21
22	\| 字段 \| 说明 \|
23	\|------\|------\|
24	\| `task_id` \| 任务 ID \|
25	\| `pipeline` \| pipeline 名称 \|
26	\| `status` \| `pending` / `running` / `completed` / `failed` \|
27	\| `progress` \| 0-100 进度 \|
28	\| `input` \| 启动任务时传入的参数 \|
29	\| `output` \| pipeline 返回的结构化结果 \|
30	\| `artifacts` \| 产物列表，包含图片、音频、视频、文本 \|
31	\| `output_dir` \| 产物目录 \|
32
33	## 通用 API
34
35	### 查询任务列表
36
37	```bash
38	curl "http://localhost:8000/api/tasks?limit=100"
39	```
40
41	### 查询任务详情
42
43	```bash
44	curl "http://localhost:8000/api/tasks/{task_id}"
45	```
46
47	### 订阅任务事件
48
49	```bash
50	curl -N "http://localhost:8000/api/tasks/{task_id}/events"
51	```
52
53	事件类型：
54
55	\| type \| 说明 \|
56	\|------\|------\|
57	\| `snapshot` \| 当前任务快照 \|
58	\| `progress` \| 进度更新 \|
59	\| `artifact` \| 新产物生成 \|
60	\| `completed` \| 任务完成 \|
61	\| `failed` \| 任务失败 \|
62
63	### 删除任务
64
65	```bash
66	curl -X DELETE "http://localhost:8000/api/tasks/{task_id}"
67	```
68
69	删除任务会同步删除任务元数据和对应产物目录。
70
71	## 上传媒体文件
72
73	文艺短视频不需要上传文件；动作迁移和数字人口播常需要上传图片或视频。
74
75	```bash
76	curl -X POST "http://localhost:8000/api/upload_media" \
77	-F "file=@/path/to/file.png"
78	```
79
80	响应：
81
82	```json
83	{
84	"filename": "file.png",
85	"file_path": "/absolute/path/to/backend/code/result/task/uploads/xxx.png"
86	}
87	```
88
89	`file_path` 可直接作为 pipeline 请求参数传入。
90
91	## 模型列表与能力筛选
92
93	前端和 Agent 都应通过模型能力标签筛选可用模型。
94
95	```bash
96	curl "http://localhost:8000/api/models?media_type=image&ability=text_to_image&verified_only=true"
97	curl "http://localhost:8000/api/models?media_type=image&ability=reference_image&verified_only=true"
98	curl "http://localhost:8000/api/models?media_type=video&ability=action_transfer&verified_only=true"
99	curl "http://localhost:8000/api/models?media_type=video&ability=digital_human&verified_only=true"
100	```
101
102	常用能力：
103
104	\| media_type \| ability \| 用途 \|
105	\|------------\|---------\|------\|
106	\| `image` \| `text_to_image` \| 文艺短视频文生图 \|
107	\| `video` \| `image_to_video` \| 文艺短视频动态视频模式 \|
108	\| `image` \| `reference_image` \| 数字人口播商品/人物参考图 \|
109	\| `video` \| `action_transfer` \| 动作迁移 \|
110	\| `video` \| `digital_human` \| 数字人口播 \|
111
112	## 前端入口
113
114	\| 页面 \| URL \|
115	\|------\|-----\|
116	\| Video-Claw 主流程 \| `http://localhost:3000/` \|
117	\| 临时工作台 \| `http://localhost:3000/sandbox` \|
118	\| 文艺短视频 \| `http://localhost:3000/pipelines/standard` \|
119	\| 动作迁移 \| `http://localhost:3000/pipelines/action-transfer` \|
120	\| 数字人口播 \| `http://localhost:3000/pipelines/digital-human` \|
121
122	## 注意事项
123
124	1. Pipeline 是一次输入、后台执行，中间无需人工干预。
125	2. 前端不轮询任务进度，而是通过 `/api/tasks/{task_id}/events` 订阅。
126	3. 产物显示时只展示图片、音频、视频；日志不作为任务状态内容展示。
127	4. 历史记录按 pipeline 分类展示，并支持删除。
128

128 lines MARKDOWN