backend/backend_app/api/voice/README.md

语音生成API文档

概述

语音生成API提供企业级文本到语音转换服务，支持多种语音类型、语速、音调、音量等参数控制，可生成MP3、WAV、OGG等多种格式的音频文件。

API端点

1. 生成语音

POST /api/v1/voice/generate

请求体：

{
  "text": "欢迎使用企业级语音生成服务",
  "voice_type": "female",
  "speed": "normal",
  "pitch": 1.0,
  "volume": 1.0,
  "output_format": "mp3",
  "language": "zh-CN",
  "user_id": "user_12345"
}

参数说明：

参数	类型	必填	默认值	说明
text	string	是	-	要转换的文本内容，最长5000字符
voice_type	string	否	female	语音类型：female(甜美女生)、male(阳光男生)、child(卡通童声)、professional(专业播音)
speed	string	否	normal	语速：slow(慢速)、normal(正常)、fast(快速)
pitch	float	否	1.0	音调，范围0.5-2.0
volume	float	否	1.0	音量，范围0.0-2.0
output_format	string	否	mp3	输出格式：mp3、wav、ogg
language	string	否	zh-CN	语言代码：zh-CN、en-US、ja-JP
user_id	string	否	null	用户ID，用于统计和配额管理

响应：

{
  "success": true,
  "voice_url": "/api/voice/files/voice_abc123.mp3",
  "voice_id": "voice_abc123",
  "duration": 12.5,
  "file_size": 256000,
  "format": "mp3",
  "text_length": 45,
  "timestamp": "2024-01-01T12:00:00"
}

2. 获取语音文件

GET /api/v1/voice/files/{voice_id}.{format}

参数：

参数	类型	必填	说明
voice_id	string	是	语音文件ID
format	string	是	文件格式：mp3、wav、ogg

响应： 返回音频文件流，Content-Type为对应的音频类型。

3. 获取支持的语音类型

GET /api/v1/voice/supported-voices

响应：

{
  "success": true,
  "voices": {
    "female": {"name": "甜美女生", "description": "清晰甜美的女声"},
    "male": {"name": "阳光男生", "description": "阳光活力的男声"},
    "child": {"name": "卡通童声", "description": "可爱活泼的童声"},
    "professional": {"name": "专业播音", "description": "专业播音员声音"}
  },
  "formats": ["mp3", "wav", "ogg"],
  "languages": ["zh-CN", "en-US", "ja-JP"],
  "timestamp": "2024-01-01T12:00:00"
}

4. 列出语音文件

GET /api/v1/voice/list?page=1&page_size=20

查询参数：

参数	类型	必填	默认值	说明
page	int	否	1	页码
page_size	int	否	20	每页数量

响应：

{
  "success": true,
  "voices": [
    {
      "voice_id": "voice_abc123",
      "filename": "voice_abc123.mp3",
      "size": 256000,
      "created_at": "2024-01-01T12:00:00",
      "format": "mp3"
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 20,
  "timestamp": "2024-01-01T12:00:00"
}

5. 删除语音文件

POST /api/v1/voice/delete

请求体：

{
  "voice_id": "voice_abc123",
  "confirm": true
}

响应：

{
  "success": true,
  "message": "语音文件已成功删除",
  "timestamp": "2024-01-01T12:00:00"
}

6. 健康检查

GET /api/v1/voice/health

响应：

{
  "status": "healthy",
  "service": "voice_generation",
  "output_dir": "./voice_outputs",
  "files_count": 10,
  "timestamp": "2024-01-01T12:00:00"
}

错误处理

所有API端点都遵循统一的错误响应格式：

{
  "detail": "错误描述信息"
}

HTTP状态码：

• 200: 请求成功
• 400: 参数错误
• 404: 资源不存在
• 500: 服务器内部错误

企业级功能

1. 多语言支持

支持中文、英文、日文等多种语言，可根据需要扩展。

2. 参数验证

对所有输入参数进行严格验证，确保数据安全性和服务稳定性。

3. 错误处理与降级

完善的错误处理机制，在主要TTS服务不可用时支持降级到备用服务。

4. 性能监控

内置性能监控和日志记录，支持实时监控服务状态。

5. 缓存机制

支持语音文件缓存，减少重复生成，提高响应速度。

部署配置

环境变量

# 语音引擎配置
VOICE_ENGINE=gtts  # gtts, pyttsx3, edge-tts, simulated
VOICE_API_KEY=your_api_key
VOICE_REGION=us-west-1

# 存储配置
STORAGE_TYPE=local  # local, s3, azure_blob, gcs
STORAGE_BUCKET=voice-bucket
STORAGE_REGION=us-west-1

# API配置
API_RATE_LIMIT=60
API_AUTH_REQUIRED=false

依赖安装

# 基本依赖
pip install fastapi uvicorn python-multipart

# 语音生成依赖（根据选择的引擎）
pip install gTTS        # Google Text-to-Speech
# 或
pip install pyttsx3     # 离线TTS
# 或
pip install edge-tts    # Microsoft Edge TTS

使用示例

Python客户端

import requests

BASE_URL = "http://localhost:8000/api/v1"

def generate_voice(text, voice_type="female"):
    response = requests.post(f"{BASE_URL}/voice/generate", json={
        "text": text,
        "voice_type": voice_type,
        "output_format": "mp3",
        "language": "zh-CN"
    })

    if response.status_code == 200:
        data = response.json()
        if data["success"]:
            print(f"语音生成成功: {data['voice_url']}")
            return data
    else:
        print(f"语音生成失败: {response.text}")

    return None

JavaScript/TypeScript客户端

const API_BASE_URL = 'http://localhost:8000/api/v1';

async function generateVoice(text: string): Promise<any> {
  const response = await fetch(`${API_BASE_URL}/voice/generate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      voice_type: 'female',
      output_format: 'mp3'
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

性能优化建议

1. 启用缓存：对于重复的文本内容，启用缓存可大幅提升性能
2. 批量处理：支持批量文本转换，减少API调用次数
3. 异步处理：对于长文本，支持异步生成和状态查询
4. CDN加速：生成的语音文件可通过CDN分发，提高访问速度
5. 负载均衡：在高并发场景下，建议部署多个实例并使用负载均衡

安全注意事项

1. 输入验证：所有用户输入都应进行严格的验证和清理
2. 配额限制：根据用户等级实施API调用配额限制
3. 访问控制：敏感接口应实施身份验证和授权
4. 日志审计：记录所有API调用，便于安全审计
5. 数据加密：敏感数据在传输和存储时应加密