Pixelle-Video 如何启动 HTTP API 服务并通过健康接口检查可用性？

Pixelle-Video 如何启动 HTTP API 服务并通过健康接口检查可用性？

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video

Pixelle-Video 除了 Python SDK 和 Streamlit Web 界面，还提供一个基于 FastAPI 的 HTTP REST API 服务。如果你需要以服务端方式集成视频生成能力（比如在自己的系统里通过 HTTP 调用生成视频），第一步就是把 API 服务跑起来，并确认它是可用的。本文对应任务：在本机启动该 API 服务，然后调用健康检查接口/health验证服务存活。环境要求来自安装文档：Python 3.10 或更高版本，支持 Windows、macOS、Linux，包管理器推荐 uv（也支持 pip），参见 安装文档。

准备条件

在服务目录（即包含api/的项目根目录）下完成依赖安装。使用 uv 时：

uv sync

uv 会自动创建虚拟环境。如果使用 pip，则按 安装文档 创建虚拟环境并执行pip install -e .。安装完成后不需要额外的编译步骤，但视频生成等接口实际使用时需要按 配置说明 配置 LLM 和图像生成服务的 API 密钥——这不影响 API 服务本身的启动与健康检查。

启动 API 服务

API 服务的入口是 api/app.py，API 概览文档 给出的标准启动命令为：

uv run uvicorn api.app:app --host 0.0.0.0 --port 8000

• --host 0.0.0.0：绑定所有网络接口，允许其他机器访问；只在本机调试时可改为127.0.0.1。
• --port 8000：服务端口，默认值就是 8000（见 api/config.py 中的port: int = 8000）。

另一种等价方式是直接运行入口脚本，见 api/app.py 文件头部注释：

uv run python api/app.py --host 0.0.0.0 --port 8000 # 开发调试时可用 --reload 开启代码变更自动重载

服务启动后，日志会打印Starting server at http://0.0.0.0:8000以及 API 文档地址，此时按Ctrl+C可以停止服务。

可选：通过 Docker Compose 启动

如果使用容器部署，docker-compose.yml 中定义了api服务，启动命令为.venv/bin/python api/app.py --host 0.0.0.0 --port 8000，并将宿主机的8000端口映射到容器内。该服务还配置了基于/health接口的健康检查（curl -f http://localhost:8000/health，每 30 秒一次），Docker 会自动用它判断容器是否健康。

通过 /health 接口检查可用性

健康检查端点定义在 api/routers/health.py：GET /health，不带/api前缀（这一点可以在 api/app.py 的路由注册处看到，health 路由直接挂载在根路径下）。服务启动后执行：

curl http://localhost:8000/health

该接口返回服务状态与版本信息，响应模型HealthResponse的字段为：

{ "status": "healthy", "version": "0.1.0", "service": "Pixelle-Video API" }

上面是依据 health.py 中响应模型的默认值整理的返回结构。只要收到 HTTP 200 且返回体包含"status": "healthy"，即说明服务进程存活、HTTP 层可用。Docker Compose 的健康检查正是用curl -f（非 2xx 状态码时失败）来判定这一点的，可以照搬：curl -f http://localhost:8000/health。

其他可用于确认服务就绪的端点

• GET /：返回服务名、版本以及各功能模块（/api/llm、/api/video、/api/tasks等）的路由索引，见 api/app.py 中的根端点。
• GET /version：返回与健康检查相同结构的状态与版本信息（同样是HealthResponse）。
• Swagger UI：浏览器访问http://localhost:8000/docs，能打开交互式文档页面也说明服务正常，所有接口都可以在页面上直接试调。路径/docs、/redoc、/openapi.json均可在 api/config.py 中确认。

排查与限制

• 如果curl连接被拒绝，先确认启动命令在正确的目录（项目根目录）下执行、依赖已安装、8000 端口未被占用，服务启动成功日志（Starting server at ...）是最直接的判断依据。
• /health返回的是固定的默认值（状态healthy、版本0.1.0），它验证的是 API 进程与 HTTP 层的可用性，不会去探测 LLM、TTS 或图像生成等下游服务的连通性。真实发起视频生成请求时若报密钥或服务相关错误，需要回到 配置说明 检查服务配置。
• 除健康检查外，业务接口统一挂载在/api前缀下，例如视频生成的同步接口POST /api/video/generate/sync，参数详见 API 概览。

确认/health返回正常后，就可以继续按 API 概览 调用内容生成、视频生成与任务查询接口了。

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video