# OpenAI API 配置指南

**日期**: 2026-01-30  
**适用版本**: v1.0+

---

## 目录

1. [概述](#概述)
2. [获取 OpenAI API Key](#获取-openai-api-key)
3. [配置环境变量](#配置环境变量)
4. [支持的模型](#支持的模型)
5. [测试验证](#测试验证)
6. [常见问题](#常见问题)

---

## 概述

Jointo 项目支持使用真实的 OpenAI API 进行 AI 内容生成。配置 OpenAI API Key 后，系统将自动使用真实的 AI 模型，而非 Mock Provider。

### 支持的功能

- ✅ **图片生成**：DALL-E 3 / DALL-E 2
- ✅ **文本处理**：GPT-4 / GPT-3.5 Turbo
- ✅ **配音生成**：TTS-1 / TTS-1-HD
- ✅ **字幕生成**：Whisper-1
- ❌ **视频生成**：OpenAI 不支持（需使用 Runway 或 Pika）
- ❌ **音效生成**：OpenAI 不支持（需使用其他 Provider）

---

## 获取 OpenAI API Key

### 步骤 1：注册 OpenAI 账号

1. 访问 [OpenAI Platform](https://platform.openai.com/)
2. 点击 "Sign up" 注册账号
3. 验证邮箱并完成注册

### 步骤 2：创建 API Key

1. 登录后，访问 [API Keys 页面](https://platform.openai.com/api-keys)
2. 点击 "Create new secret key"
3. 输入 Key 名称（如：`jointo-dev`）
4. 复制生成的 API Key（**只显示一次，请妥善保存**）

### 步骤 3：充值账户（可选）

OpenAI 提供免费额度（$5），用完后需要充值：

1. 访问 [Billing 页面](https://platform.openai.com/account/billing/overview)
2. 点击 "Add payment method"
3. 添加信用卡并充值

**费用参考**（2026 年 1 月）：
- DALL-E 3 (1024x1024)：$0.040 / 张
- GPT-4 Turbo：$0.01 / 1K tokens (输入)，$0.03 / 1K tokens (输出)
- GPT-3.5 Turbo：$0.0005 / 1K tokens (输入)，$0.0015 / 1K tokens (输出)
- TTS-1：$0.015 / 1K 字符
- Whisper-1：$0.006 / 分钟

---

## 配置环境变量

### 方式 1：修改 `.env` 文件（推荐）

编辑 `server/.env` 文件，添加 OpenAI API Key：

```env
# AI 服务配置
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
```

**重要提示**：
- ✅ API Key 格式：`sk-proj-` 开头（新版）或 `sk-` 开头（旧版）
- ✅ 不要提交 API Key 到 Git（`.env` 已在 `.gitignore` 中）
- ✅ 生产环境使用独立的 API Key

### 方式 2：使用 Docker Compose 环境变量

编辑 `server/docker-compose.yml`，在 `jointo-server-app` 服务中添加：

```yaml
services:
  jointo-server-app:
    environment:
      - OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - OPENAI_BASE_URL=https://api.openai.com/v1
```

### 方式 3：使用国内代理（可选）

如果无法直接访问 OpenAI API，可以使用代理服务：

```env
# 使用代理服务（示例）
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai-proxy.com/v1
```

**常见代理服务**：
- [OpenAI-SB](https://openai-sb.com/)
- [API2D](https://api2d.com/)
- [CloseAI](https://close.ai/)

---

## 支持的模型

### 图片生成模型

| 模型名称 | 描述 | 支持尺寸 | 费用 |
|---------|------|---------|------|
| `dall-e-3` | DALL-E 3（推荐） | 1024x1024, 1792x1024, 1024x1792 | $0.040/张 |
| `dall-e-2` | DALL-E 2 | 256x256, 512x512, 1024x1024 | $0.020/张 |

**使用示例**：
```bash
curl -X POST http://localhost:6170/api/v1/ai/generate-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的小猫在花园里玩耍",
    "model": "dall-e-3",
    "width": 1024,
    "height": 1024,
    "style": "vivid",
    "quality": "standard"
  }'
```

### 文本处理模型

| 模型名称 | 描述 | 上下文长度 | 费用 |
|---------|------|-----------|------|
| `gpt-4-turbo` | GPT-4 Turbo（推荐） | 128K tokens | $0.01/$0.03 per 1K tokens |
| `gpt-4` | GPT-4 | 8K tokens | $0.03/$0.06 per 1K tokens |
| `gpt-3.5-turbo` | GPT-3.5 Turbo | 16K tokens | $0.0005/$0.0015 per 1K tokens |

**使用示例**：
```bash
curl -X POST http://localhost:6170/api/v1/ai/process-text \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "screenplay_parse",
    "text": "场景1：咖啡厅 - 白天\n张三坐在窗边...",
    "model": "gpt-4-turbo",
    "output_format": "json"
  }'
```

### 配音生成模型

| 模型名称 | 描述 | 支持语音 | 费用 |
|---------|------|---------|------|
| `tts-1` | TTS 标准版 | alloy, echo, fable, onyx, nova, shimmer | $0.015/1K 字符 |
| `tts-1-hd` | TTS 高清版 | 同上 | $0.030/1K 字符 |

**使用示例**：
```bash
curl -X POST http://localhost:6170/api/v1/ai/generate-voice \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "欢迎使用 Jointo 视频制作平台",
    "model": "tts-1",
    "voice_type": "alloy",
    "speed": 1.0,
    "language": "zh-CN"
  }'
```

### 字幕生成模型

| 模型名称 | 描述 | 支持语言 | 费用 |
|---------|------|---------|------|
| `whisper-1` | Whisper | 99+ 语言 | $0.006/分钟 |

**使用示例**：
```bash
curl -X POST http://localhost:6170/api/v1/ai/generate-subtitle \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "model": "whisper-1",
    "language": "zh"
  }'
```

---

## 测试验证

### 步骤 1：重启服务

配置 API Key 后，需要重启服务以加载新配置：

```bash
# 重启 FastAPI 应用
docker restart jointo-server-app

# 重启 Celery Worker（AI 任务）
docker restart jointo-server-celery-ai
```

### 步骤 2：检查日志

查看日志确认 OpenAI Provider 已启用：

```bash
# 查看应用日志
docker logs jointo-server-app | grep -i openai

# 查看 Celery Worker 日志
docker logs jointo-server-celery-ai | grep -i openai
```

**预期输出**：
```
INFO - 初始化 OpenAI Provider: model=dall-e-3, base_url=https://api.openai.com/v1
INFO - 创建 OpenAI Provider: model=dall-e-3
```

**如果看到以下日志，说明未配置 API Key**：
```
WARNING - OPENAI_API_KEY 未配置，使用 Mock Provider: model=dall-e-3
```

### 步骤 3：测试图片生成

使用 Swagger UI 或 curl 测试图片生成：

#### 方式 1：Swagger UI（推荐）

1. 访问 http://localhost:6170/docs
2. 找到 `POST /api/v1/ai/generate-image`
3. 点击 "Try it out"
4. 填写参数：
   ```json
   {
     "prompt": "一只可爱的小猫在花园里玩耍",
     "model": "dall-e-3",
     "width": 1024,
     "height": 1024
   }
   ```
5. 点击 "Execute"

#### 方式 2：使用测试脚本

```bash
# 使用端到端测试脚本
docker exec jointo-server-app python scripts/test_ai_image_generation_e2e.py
```

#### 方式 3：使用 curl

```bash
# 1. 登录获取 token
TOKEN=$(curl -X POST http://localhost:6170/api/v1/auth/login/phone \
  -H "Content-Type: application/json" \
  -d '{"phone": "+8613800138000", "country_code": "+86", "code": "6666"}' \
  | jq -r '.data.access_token')

# 2. 调用图片生成 API
curl -X POST http://localhost:6170/api/v1/ai/generate-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的小猫在花园里玩耍",
    "model": "dall-e-3",
    "width": 1024,
    "height": 1024
  }' | jq

# 3. 查询任务状态
JOB_ID="<从上一步获取的 job_id>"
curl http://localhost:6170/api/v1/ai/jobs/$JOB_ID \
  -H "Authorization: Bearer $TOKEN" | jq
```

### 步骤 4：验证文件存储

生成成功后，检查文件是否上传到 MinIO：

1. 访问 MinIO Console：http://localhost:6185
2. 登录（用户名：`ZVrux4QA6Wy1yLjQ6tg5`，密码：`8n44dPjvV79vUmCSZLxuM10sRQoJq9HjfhXzx5xX`）
3. 进入 `jointo` bucket
4. 查看 `ai-generated/images/` 目录
5. 确认文件已上传

---

## 常见问题

### Q1: API Key 无效

**错误信息**：
```
401 Unauthorized: Incorrect API key provided
```

**解决方案**：
1. 检查 API Key 是否正确复制（不要有多余空格）
2. 确认 API Key 未过期或被撤销
3. 在 [OpenAI Platform](https://platform.openai.com/api-keys) 重新生成 API Key

### Q2: 余额不足

**错误信息**：
```
429 Too Many Requests: You exceeded your current quota
```

**解决方案**：
1. 访问 [Billing 页面](https://platform.openai.com/account/billing/overview)
2. 检查账户余额
3. 充值或等待免费额度重置

### Q3: 网络连接失败

**错误信息**：
```
httpx.ConnectError: Connection refused
```

**解决方案**：
1. 检查网络连接
2. 确认可以访问 `https://api.openai.com`
3. 如果在国内，考虑使用代理服务（见上文）

### Q4: 模型不支持

**错误信息**：
```
NotImplementedError: OpenAI 不支持视频生成
```

**解决方案**：
- OpenAI 不支持视频生成和音效生成
- 视频生成请使用 Runway 或 Pika
- 音效生成请使用其他 AI Provider

### Q5: 如何切换回 Mock Provider

如果想临时使用 Mock Provider（不消耗 API 额度）：

**方式 1：清空 API Key**
```env
OPENAI_API_KEY=
```

**方式 2：在代码中强制使用 Mock**
```python
# 在调用 AI Service 时传入 config
config = {'use_mock': True}
provider = AIProviderFactory.create_provider('dall-e-3', config)
```

### Q6: 如何监控 API 使用量

1. 访问 [OpenAI Usage 页面](https://platform.openai.com/account/usage)
2. 查看每日/每月使用量
3. 设置使用限额（Usage limits）

### Q7: 生成的图片在哪里

生成的图片会自动下载并上传到自有 OSS（MinIO）：

1. **开发环境**：MinIO（http://localhost:6185）
2. **生产环境**：阿里云 OSS 或其他云存储
3. **数据库记录**：`ai_jobs` 表的 `output_data` 字段

**output_data 示例**：
```json
{
  "file_url": "http://localhost:6185/jointo/ai-generated/images/user_id/checksum.png",
  "file_size": 1024000,
  "checksum": "abc123...",
  "mime_type": "image/png",
  "storage_provider": "minio",
  "storage_path": "ai-generated/images/user_id/checksum.png",
  "original_url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
}
```

---

## 相关文档

- [AI Service 设计文档](../../requirements/backend/04-services/ai/ai-service.md)
- [File Storage Service 文档](../../requirements/backend/04-services/resource/file-storage-service.md)
- [AI API 测试指南](./ai-api-testing.md)
- [OpenAI API 官方文档](https://platform.openai.com/docs/api-reference)

---

## 总结

配置 OpenAI API Key 后，Jointo 项目将自动使用真实的 AI 模型进行内容生成。所有生成的文件会自动下载并上传到自有 OSS，确保数据主权和文件持久化。

**快速开始**：
1. 获取 OpenAI API Key
2. 配置 `server/.env` 文件
3. 重启服务
4. 测试图片生成 API
5. 验证文件上传到 MinIO

如有问题，请查看日志或联系技术支持。