11 KiB

Raw Blame History

OpenAI API 配置指南

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

概述

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 账号

访问 OpenAI Platform
点击 "Sign up" 注册账号
验证邮箱并完成注册

步骤 2：创建 API Key

登录后，访问 API Keys 页面
点击 "Create new secret key"
输入 Key 名称（如：jointo-dev）
复制生成的 API Key（只显示一次，请妥善保存）

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

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

访问 Billing 页面
点击 "Add payment method"
添加信用卡并充值

费用参考（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：

# 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 服务中添加：

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

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

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

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

常见代理服务：

支持的模型

图片生成模型

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

使用示例：

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

使用示例：

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 字符

使用示例：

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/分钟

使用示例：

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 后，需要重启服务以加载新配置：

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

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

步骤 2：检查日志

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

# 查看应用日志
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（推荐）

访问 http://localhost:6170/docs
找到 POST /api/v1/ai/generate-image
点击 "Try it out"

填写参数：

{
  "prompt": "一只可爱的小猫在花园里玩耍",
  "model": "dall-e-3",
  "width": 1024,
  "height": 1024
}

点击 "Execute"

方式 2：使用测试脚本

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

方式 3：使用 curl

# 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：

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

常见问题

Q1: API Key 无效

错误信息：

401 Unauthorized: Incorrect API key provided

解决方案：

检查 API Key 是否正确复制（不要有多余空格）
确认 API Key 未过期或被撤销
在 OpenAI Platform 重新生成 API Key

Q2: 余额不足

错误信息：

429 Too Many Requests: You exceeded your current quota

解决方案：

访问 Billing 页面
检查账户余额
充值或等待免费额度重置

Q3: 网络连接失败

错误信息：

httpx.ConnectError: Connection refused

解决方案：

检查网络连接
确认可以访问 https://api.openai.com
如果在国内，考虑使用代理服务（见上文）

Q4: 模型不支持

错误信息：

NotImplementedError: OpenAI 不支持视频生成

解决方案：

OpenAI 不支持视频生成和音效生成
视频生成请使用 Runway 或 Pika
音效生成请使用其他 AI Provider

Q5: 如何切换回 Mock Provider

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

方式 1：清空 API Key

OPENAI_API_KEY=

方式 2：在代码中强制使用 Mock

# 在调用 AI Service 时传入 config
config = {'use_mock': True}
provider = AIProviderFactory.create_provider('dall-e-3', config)

Q6: 如何监控 API 使用量

访问 OpenAI Usage 页面
查看每日/每月使用量
设置使用限额（Usage limits）

Q7: 生成的图片在哪里

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

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

output_data 示例：

{
  "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/..."
}

总结

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

快速开始：

获取 OpenAI API Key
配置 server/.env 文件
重启服务
测试图片生成 API
验证文件上传到 MinIO

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

11 KiB Raw Blame History

OpenAI API 配置指南

目录

概述

支持的功能

获取 OpenAI API Key

步骤 1：注册 OpenAI 账号

步骤 2：创建 API Key

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

配置环境变量

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

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

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

支持的模型

图片生成模型

文本处理模型

配音生成模型

字幕生成模型

测试验证

步骤 1：重启服务

步骤 2：检查日志

步骤 3：测试图片生成

方式 1：Swagger UI（推荐）

方式 2：使用测试脚本

方式 3：使用 curl

步骤 4：验证文件存储

常见问题

Q1: API Key 无效

Q2: 余额不足

Q3: 网络连接失败

Q4: 模型不支持

Q5: 如何切换回 Mock Provider

Q6: 如何监控 API 使用量

Q7: 生成的图片在哪里

相关文档

总结

11 KiB

Raw Blame History

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