Wan2.1/I2V-FastAPI文档.md

图像到视频生成服务API文档

一、功能概述

基于Wan2.1-I2V-14B-480P模型实现图像到视频生成，核心功能包括：

1. 异步任务队列：支持多任务排队和并发控制（最大2个并行任务）
2. 智能分辨率适配：
   • 支持自动计算最佳分辨率（保持原图比例）
   • 支持手动指定分辨率（480x832/832x480）
3. 资源管理：
   • 显存优化（bfloat16精度）
   • 生成文件自动清理（默认1小时）
4. 安全认证：基于API Key的Bearer Token验证
5. 任务控制：支持任务提交/状态查询/取消操作

技术栈：

• FastAPI框架
• CUDA加速
• 异步任务处理
• Diffusers推理库

---

二、接口说明

1. 提交生成任务

POST /video/submit

{
  "model": "Wan2.1-I2V-14B-480P",
  "prompt": "A dancing cat in the style of Van Gogh",
  "image_url": "https://example.com/input.jpg",
  "image_size": "auto",
  "num_frames": 81,
  "guidance_scale": 3.0,
  "infer_steps": 30
}

响应示例：

{
  "requestId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

2. 查询任务状态

POST /video/status

{
  "requestId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

响应示例：

{
  "status": "Succeed",
  "results": {
    "videos": [{"url": "http://localhost:8088/videos/abcd1234.mp4"}],
    "timings": {"inference": 90},
    "seed": 123456
  }
}

3. 取消任务

POST /video/cancel

{
  "requestId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

响应示例：

{
  "status": "Succeed"
}

---

三、Postman使用指南

1. 基础配置

• 服务器地址：http://ip地址:8088
• 认证方式：Bearer Token
• Token值：需替换为有效API Key

2. 提交任务

1. 选择POST方法，URL填写/video/submit
2. Headers添加：

   Authorization: Bearer YOUR_API_KEY
   Content-Type: application/json
   

3. Body示例（图像生成视频）：

   {
     "prompt": "Sunset scene with mountains",
     "image_url": "https://example.com/mountain.jpg",
     "image_size": "auto",
     "num_frames": 50
   }
   

3. 特殊处理

• 图像下载失败：返回400错误，包含具体原因（如URL无效/超时）
• 显存不足：返回500错误并提示降低分辨率

---

四、参数规范

参数名	允许值范围	必填	说明
image_url	有效HTTP/HTTPS URL	是	输入图像地址
prompt	10-500字符	是	视频内容描述
image_size	"480x832", "832x480", "auto"	是	auto模式自动适配原图比例
num_frames	24-120	是	视频总帧数
guidance_scale	1.0-20.0	是	文本引导强度
infer_steps	20-100	是	推理步数
seed	0-2147483647	否	随机种子

---

五、状态码说明

状态码	含义
202	任务已接受
400	图像下载失败/参数错误
401	认证失败
404	任务不存在
422	参数校验失败
500	服务端错误（显存不足/模型异常等）

---

六、特殊功能说明

1. 智能分辨率适配：

   • 当image_size="auto"时，自动计算符合模型要求的最优分辨率
   • 保持原始图像宽高比，最大像素面积不超过399,360（约640x624）

2. 图像预处理：

   • 自动转换为RGB模式
   • 根据目标分辨率进行等比缩放

重要提示：输入图像URL需保证公开可访问，私有资源需提供有效鉴权

提示 ：访问http://服务器地址:8088/docs可查看交互式API文档，支持在线测试所有接口