小鱼开发
689aef0946
规范: <source_type>_<user_id>_<timestamp_ms>
前端 4 处（projectId → userId）:
- VideoGeneration: video_${userId}_${Date.now()}
- SubtitleBurning: subtitle_burn_${userId}_${Date.now()}
- VideoCompose: compose_${userId}_${Date.now()}
- CoverDesign: cover_design_${userId}_${Date.now()}
后端 4 处（浮点秒 → 毫秒整数）:
- script.py polish: polish_${userId}_${int(time.time()*1000)}
- script.py title: title_${userId}_${int(time.time()*1000)}
- voice.py TTS: tts_${userId}_${int(time.time()*1000)}
- voice.py voice_clone: voice_clone_${userId}_${ts}_${voice_id}
（原裸传第三方 voice_id，现包装为规范格式）
Refs: P2-1
美家卡智影 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。
云端部署后：
- 修改前端
src/api/client.ts中的PYTHON_API_BASE_URL - 更新
tauri.conf.jsonCSP 配置，添加云端域名到connect-src
许可
MIT