sora2api/README.md

# Sora2API

<div align="center">

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/fastapi-0.119.0-green.svg)](https://fastapi.tiangolo.com/)
[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://www.docker.com/)

**一个功能完整的 OpenAI 兼容 API 服务，为 Sora 提供统一的接口**

</div>

---

## 📋 目录

- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [使用指南](#使用指南)
- [架构设计](#架构设计)
- [许可证](#许可证)

---

## ✨ 功能特性

### 核心功能
- 🎨 **文生图** - 根据文本描述生成图片
- 🖼️ **图生图** - 基于上传的图片进行创意变换
- 🎬 **文生视频** - 根据文本描述生成视频
- 🎥 **图生视频** - 基于图片生成相关视频
- 📊 **多尺寸支持** - 横屏、竖屏等多种规格

### 高级特性
- 🔐 **Token 管理** - 支持多 Token 管理和轮询负载均衡
- 🌐 **代理支持** - 支持 HTTP 和 SOCKS5 代理
- 📝 **详细日志** - 完整的请求/响应日志记录
- 🔄 **异步处理** - 高效的异步任务处理
- 💾 **数据持久化** - SQLite 数据库存储
- 🎯 **OpenAI 兼容** - 完全兼容 OpenAI API 格式
- 🛡️ **安全认证** - API Key 验证和权限管理
- 📱 **Web 管理界面** - 直观的管理后台

### 可靠性
- ⚡ **自动重试** - 智能重试机制
- 🔒 **错误处理** - 完善的错误处理和恢复
- 📊 **性能监控** - Token 使用统计和监控
- 🚫 **速率限制** - 防止滥用的限流机制

---

## 🚀 快速开始

### 前置要求

- Docker 和 Docker Compose（推荐）
- 或 Python 3.8+

### 方式一：Docker 部署（推荐）

#### 标准模式（不使用代理）

```bash
# 克隆项目
git clone https://github.com/TheSmallHanCat/sora2api.git
cd sora2api

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f
```

#### WARP 模式（使用代理）

```bash
# 使用 WARP 代理启动
docker-compose -f docker-compose.warp.yml up -d

# 查看日志
docker-compose -f docker-compose.warp.yml logs -f
```

### 方式二：本地部署

```bash
# 克隆项目
git clone https://github.com/TheSmallHanCat/sora2api.git
cd sora2api

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
python main.py
```

### 首次启动

服务启动后，访问管理后台进行初始化配置：

- **地址**: http://localhost:8000
- **用户名**: `admin`
- **密码**: `admin`

⚠️ **重要**: 首次登录后请立即修改密码！

---

## 📖 使用指南

### 管理后台

访问 http://localhost:8000（或你的服务器 IP/域名）

#### 主要功能

1. **Token 管理**
   - 添加/删除 Sora Token
   - 查看 Token 状态和使用统计
   - 设置 Token 过期时间
   - 编辑 Token 备注信息

2. **代理配置**
   - 启用/禁用代理
   - 配置代理地址（支持 HTTP 和 SOCKS5）

3. **调试模式**
   - 启用详细日志记录
   - 查看 API 请求/响应详情

4. **系统配置**
   - 修改管理员密码
   - 修改 API Key
   - 配置冷却阈值和错误限制

### API 调用

#### 基本信息（使用OpenAI标准格式）

- **端点**: `http://localhost:8000/v1/chat/completions`
- **认证**: 在请求头中添加 `Authorization: Bearer YOUR_API_KEY`
- **默认 API Key**: `han1234`（建议修改）

#### 支持的模型

| 模型 | 说明 | 输入 | 输出 |
|------|------|------|------|
| `sora-image` | 文生图（默认横屏） | 文本/图片 | 图片 |
| `sora-image-landscape` | 文生图（横屏） | 文本/图片 | 图片 |
| `sora-image-portrait` | 文生图（竖屏） | 文本/图片 | 图片 |
| `sora-video` | 文生视频（默认横屏） | 文本/图片 | 视频 |
| `sora-video-landscape` | 文生视频（横屏） | 文本/图片 | 视频 |
| `sora-video-portrait` | 文生视频（竖屏） | 文本/图片 | 视频 |

#### 请求示例

**文生图**

```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-image",
    "messages": [
      {
        "role": "user",
        "content": "一只可爱的小猫咪"
      }
    ]
  }'
```

**图生图**

```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-image",
    "messages": [
      {
        "role": "user",
        "content": "将这张图片变成油画风格"
      }
    ],
    "image": "base64_encoded_image_data"
  }'
```

**文生视频**

```bash
curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-video",
    "messages": [
      {
        "role": "user",
        "content": "一只小猫在草地上奔跑"
      }
    ]
  }'
```

#### 响应示例

```json
{
  "id": "chatcmpl-8p8fk9x",
  "object": "text_completion",
  "created": 1699564800,
  "model": "sora-image",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "<img src=\"https://example.com/image.jpg\" />"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 0,
    "total_tokens": 10
  }
}
```

---

## 🏗️ 架构设计

### 系统架构

```
┌─────────────────────────────────────────┐
│         前端 (Web UI)                    │
│  • Vue3 管理界面                        │
│  • Token 管理                           │
│  • 配置管理                             │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         API 层 (FastAPI)                 │
│  • OpenAI 兼容接口                      │
│  • 管理接口                             │
│  • 认证授权                             │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         业务层 (Services)                │
│  • Token 管理                           │
│  • 负载均衡                             │
│  • 生成处理                             │
│  • 日志记录                             │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         数据层 (SQLite)                  │
│  • Token 存储                           │
│  • 任务记录                             │
│  • 日志存储                             │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         Sora API (上游)                  │
│  • 图片生成                             │
│  • 视频生成                             │
└─────────────────────────────────────────┘
```

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

感谢所有贡献者和使用者的支持！

---

## 📞 联系方式

- 提交 Issue：[GitHub Issues](https://github.com/TheSmallHanCat/sora2api/issues)
- 讨论：[GitHub Discussions](https://github.com/TheSmallHanCat/sora2api/discussions)

---

**⭐ 如果这个项目对你有帮助，请给个 Star！**