当前位置：首页 > news >正文

Wan2.2-I2V-A14B API服务详解：FastAPI封装+Swagger文档+curl调用示例

news 2026/5/14 23:57:29

Wan2.2-I2V-A14B API服务详解：FastAPI封装+Swagger文档+curl调用示例

1. API服务概述

Wan2.2-I2V-A14B API服务基于FastAPI框架构建，提供了完整的文生视频推理接口。该服务专为开发者设计，支持通过HTTP请求直接调用模型能力，适用于批量生成、系统集成等场景。

核心特性：

标准化RESTful接口设计
自动生成的交互式Swagger文档
高性能异步处理架构
详细的错误代码和状态返回
支持多并发请求处理

2. 服务启动与配置

2.1 启动API服务

服务启动脚本已内置在镜像中，执行以下命令即可启动：

cd /workspace bash start_api.sh

服务默认监听8000端口，启动成功后会在终端显示如下信息：

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

2.2 服务配置参数

通过修改/workspace/config/api_config.yaml文件可以调整服务参数：

server: host: "0.0.0.0" # 监听地址 port: 8000 # 监听端口 workers: 2 # 工作进程数 timeout: 300 # 请求超时时间(秒) model: max_duration: 30 # 最大视频时长(秒) max_resolution: "1920x1080" # 最大分辨率 default_fps: 24 # 默认帧率

修改配置后需要重启服务生效。

3. API接口详解

3.1 交互式文档访问

服务启动后，可以通过以下地址访问自动生成的Swagger文档：

http://<服务器IP>:8000/docs

文档界面提供了：

所有可用API的详细说明
参数格式和示例
在线测试功能
返回结果示例

3.2 核心API接口

3.2.1 视频生成接口

端点：POST /api/v1/generate

功能：根据文本描述生成视频

请求参数（JSON格式）：

{ "prompt": "夕阳下的海边沙滩，海浪缓缓拍打岸边", "duration": 10, "resolution": "1920x1080", "fps": 24, "seed": 42, "output_format": "mp4" }

参数说明：

prompt：视频描述文本（必填）
duration：视频时长，秒（可选，默认10）
resolution：分辨率，格式"宽x高"（可选，默认"1920x1080"）
fps：帧率（可选，默认24）
seed：随机种子（可选）
output_format：输出格式（可选，"mp4"或"gif"）

3.2.2 任务状态查询

端点：GET /api/v1/status/{task_id}

功能：查询视频生成任务状态

响应示例：

{ "status": "completed", "progress": 100, "video_url": "/output/abcd1234.mp4", "created_at": "2024-03-20T10:00:00Z" }

3.3 返回状态码

状态码	说明
200	请求成功
400	参数错误
422	参数验证失败
500	服务器内部错误
503	服务繁忙

4. 调用示例

4.1 使用curl调用API

生成视频的基本调用示例：

curl -X POST "http://localhost:8000/api/v1/generate" \ -H "Content-Type: application/json" \ -d '{ "prompt": "城市夜景，高楼大厦灯光闪烁，车流穿梭", "duration": 8, "resolution": "1280x720" }'

成功响应示例：

{ "task_id": "abcd1234", "status": "queued", "message": "Task accepted" }

4.2 Python调用示例

使用Python的requests库调用API：

import requests import time api_url = "http://localhost:8000/api/v1/generate" headers = {"Content-Type": "application/json"} # 提交生成任务 response = requests.post(api_url, json={ "prompt": "森林中的小鹿在清晨阳光下漫步", "duration": 5, "resolution": "1920x1080" }, headers=headers) task_id = response.json()["task_id"] # 轮询任务状态 while True: status_response = requests.get(f"http://localhost:8000/api/v1/status/{task_id}") status_data = status_response.json() if status_data["status"] == "completed": print(f"视频生成完成，下载地址: {status_data['video_url']}") break elif status_data["status"] == "failed": print("视频生成失败") break print(f"进度: {status_data['progress']}%") time.sleep(5)

4.3 批量处理示例

对于批量生成需求，建议使用异步方式：

import asyncio import aiohttp async def generate_video(session, prompt): async with session.post( "http://localhost:8000/api/v1/generate", json={"prompt": prompt, "duration": 5} ) as response: return await response.json() async def main(): prompts = [ "日出时分的山脉云海", "雨后的城市街道倒影", "星空下的沙漠营地" ] async with aiohttp.ClientSession() as session: tasks = [generate_video(session, prompt) for prompt in prompts] results = await asyncio.gather(*tasks) print(results) asyncio.run(main())