meijiaka-zy/python-api

美家卡智影 API

美家卡智影后端服务 - 基于 FastAPI + Redis 的 AI 视频创作 API。

技术栈

组件	技术	版本
Web 框架	FastAPI	^0.110.0
数据库	PostgreSQL	15+
ORM	SQLAlchemy	2.0+ (异步)
缓存/状态	Redis	7.x
异步调度	Async Engine (Slot Scheduler)	Python asyncio
部署	Docker + Docker Compose	-

快速开始

1. 环境准备

确保已安装：

• Python 3.11+
• Docker & Docker Compose（推荐）
• 或本地 PostgreSQL + Redis

2. 使用 Docker Compose 启动（推荐）

# 1. 克隆项目后进入目录
cd python-api

# 2. 复制环境变量配置
cp .env.example .env

# 3. 启动所有服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f api

# 5. 服务地址
# API: http://localhost:8080
# 文档: http://localhost:8080/docs

3. 本地开发

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. 安装依赖
pip install -e ".[dev]"

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，修改数据库连接等配置

# 4. 启动 PostgreSQL 和 Redis（Docker）
docker-compose up -d db redis

# 5. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 7. 启动 Async Engine Scheduler（另开终端）
python -m app.scheduler.main

项目结构

python-api/
├── app/                    # 主应用代码
│   ├── api/v1/            # API 路由
│   ├── core/              # 核心工具（安全、异常）
│   ├── db/                # 数据库配置
│   ├── models/            # SQLAlchemy 模型
│   ├── schemas/           # Pydantic Schema
│   ├── services/          # 业务逻辑
│   ├── scheduler/         # Async Engine 异步任务调度
│   ├── ai/                # AI 模型相关
│   ├── utils/             # 工具函数
│   ├── config.py          # 配置管理
│   └── main.py            # FastAPI 入口
├── docker-compose.yml     # Docker 编排
├── Dockerfile             # Docker 镜像
├── pyproject.toml         # 项目依赖
└── README.md              # 本文档

数据模型

核心实体

• User - 用户/设备（设备 ID + JWT 认证）
• Project - 视频创作项目
• ScriptSegment - 脚本分镜
• MediaAsset - 媒体元数据（音频/视频/封面）
• TaskQueue - 异步任务队列

API 路由

模块	接口	说明
auth	POST /auth/send-code	发送验证码
	POST /auth/login	登录
	POST /auth/refresh	刷新 Token
	POST /auth/logout	登出
	GET /auth/me	获取用户信息
	PATCH /auth/me	更新用户信息
system	GET /system/version	版本信息
events	GET /events	SSE 事件流
tasks	POST /tasks/{type}	创建异步任务
	GET /tasks	任务列表
	GET /tasks/{id}	任务状态
	GET /tasks/{id}/result	任务结果
script	GET /script/categories	脚本分类
	POST /script/polish	文案润色
	POST /script/generate-title	生成标题
voice	GET /voice/voices	音色列表
	POST /voice/synthesize	TTS 合成
	POST /voice/clone/submit	提交声音复刻
	GET /voice/clone/query/{id}	查询复刻状态
caption	POST /caption/ata/align	自动字幕打轴
upload	POST /upload/video	上传视频
	POST /upload/audio	上传音频
vidu	POST /vidu/callback	Vidu 回调
materials	POST /materials/match	素材匹配
	POST /materials/batch-match	批量素材匹配
cover	GET /cover-backgrounds	封面背景图
points	GET /points/balance	积分余额
	GET /points/transactions	积分流水
	POST /points/recharge	创建充值订单
	POST /points/recharge/notify	微信支付回调
	GET /points/recharge/query/{id}	查询充值订单
	GET /points/recharge-options	充值档位
	GET /points/chargeable-types	扣费业务类型
	GET /points/rules	积分计费规则
	POST /points/consume	消费积分

环境变量

见 .env.example，主要配置项：

变量	说明	默认值
DATABASE_URL	PostgreSQL 连接字符串	postgresql+asyncpg://postgres:postgres@localhost:5432/meijiaka_zy
REDIS_URL	Redis 连接字符串	redis://localhost:6379/0
SECRET_KEY	JWT 签名密钥	必须修改
OPENAI_API_KEY	OpenAI API Key	-
CORS_ORIGINS	允许的跨域来源	http://localhost:1420

开发规范

代码风格

# 格式化
black app/

# 检查
ruff check app/
mypy app/

# 测试
pytest

提交规范

• feat: 新功能
• fix: 修复
• docs: 文档
• refactor: 重构
• test: 测试

与前端集成

Tauri 前端默认连接 http://127.0.0.1:8080/api/v1。

云端部署后：

1. 修改前端 src/api/client.ts 中的 PYTHON_API_BASE_URL
2. 更新 tauri.conf.json CSP 配置，添加云端域名到 connect-src

许可

MIT