API_GUIDE.md

# MoneyPrinterTurbo API 使用指南

## API 密钥配置

### 在 Huggingface Spaces 中配置环境变量

在 Huggingface Spaces 的 Settings → Repository secrets 中添加以下环境变量：

#### 必需的环境变量

```bash
# MoneyPrinterTurbo API 访问密钥（用于外部调用API）
MONEYPRINTER_API_KEY=your_api_key_here

# LLM 提供商 API 密钥（至少选择一个）
DEEPSEEK_API_KEY=your_deepseek_key_here          # 推荐：国内可直接访问
MOONSHOT_API_KEY=your_moonshot_key_here          # 推荐：国内可直接访问
OPENAI_API_KEY=your_openai_key_here

# 视频素材源 API 密钥（至少选择一个）
PEXELS_API_KEY=your_pexels_key_here              # 推荐：免费，质量高
PIXABAY_API_KEY=your_pixabay_key_here
```

#### 可选的环境变量

```bash
# Azure 语音服务（用于高质量语音合成）
AZURE_SPEECH_KEY=your_azure_speech_key
AZURE_SPEECH_REGION=your_azure_region           # 例如：eastus
```

## API 使用示例

### 1. 生成完整视频

```python
import requests
import json

# API 配置
base_url = "https://your-space-name-your-username.hf.space"
api_key = "your_moneyprinter_api_key"

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

# 视频生成请求
video_data = {
    "video_subject": "春天的花海",
    "video_script": "",  # 留空则自动生成
    "video_aspect": "9:16",  # 竖屏
    "video_clip_duration": 3,
    "video_count": 1,
    "video_source": "pexels",
    "voice_name": "zh-CN-XiaoxiaoNeural",
    "voice_rate": 1.0,
    "voice_volume": 1.0,
    "subtitle_enabled": True,
    "font_size": 60,
    "text_fore_color": "#FFFFFF"
}

# 发送请求
response = requests.post(
    f"{base_url}/videos",
    headers=headers,
    json=video_data
)

if response.status_code == 200:
    result = response.json()
    task_id = result["data"]["task_id"]
    print(f"任务创建成功，ID: {task_id}")
else:
    print(f"请求失败: {response.text}")
```

### 2. 查询任务状态

```python
# 查询任务状态
def check_task_status(task_id):
    response = requests.get(
        f"{base_url}/tasks/{task_id}",
        headers=headers
    )
    
    if response.status_code == 200:
        task_info = response.json()["data"]
        print(f"任务状态: {task_info.get('state')}")
        print(f"进度: {task_info.get('progress', 0)}%")
        
        if "videos" in task_info:
            print("生成的视频:")
            for video_url in task_info["videos"]:
                print(f"  - {video_url}")
        
        return task_info
    else:
        print(f"查询失败: {response.text}")
        return None

# 轮询任务状态直到完成
import time

task_info = None
while True:
    task_info = check_task_status(task_id)
    if task_info and task_info.get("state") == 1:  # 完成状态
        break
    elif task_info and task_info.get("state") == -1:  # 失败状态
        print("任务失败")
        break
    
    time.sleep(10)  # 等待10秒后再次查询
```

### 3. 仅生成音频

```python
audio_data = {
    "video_script": "这是一段测试音频文本",
    "voice_name": "zh-CN-XiaoxiaoNeural",
    "voice_rate": 1.0,
    "voice_volume": 1.0
}

response = requests.post(
    f"{base_url}/audio",
    headers=headers,
    json=audio_data
)
```

### 4. 仅生成字幕

```python
subtitle_data = {
    "video_script": "这是一段测试字幕文本",
    "voice_name": "zh-CN-XiaoxiaoNeural",
    "subtitle_enabled": True,
    "font_size": 60
}

response = requests.post(
    f"{base_url}/subtitle",
    headers=headers,
    json=subtitle_data
)
```

## JavaScript/Node.js 示例

```javascript
const axios = require('axios');

const baseURL = 'https://your-space-name-your-username.hf.space';
const apiKey = 'your_moneyprinter_api_key';

const headers = {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
};

async function generateVideo() {
    try {
        const response = await axios.post(`${baseURL}/videos`, {
            video_subject: "人工智能的发展",
            video_aspect: "16:9",
            video_clip_duration: 5,
            video_source: "pexels",
            voice_name: "zh-CN-XiaoxiaoNeural"
        }, { headers });
        
        const taskId = response.data.data.task_id;
        console.log(`任务创建成功，ID: ${taskId}`);
        
        // 轮询任务状态
        const checkStatus = setInterval(async () => {
            const statusResponse = await axios.get(
                `${baseURL}/tasks/${taskId}`,
                { headers }
            );
            
            const taskInfo = statusResponse.data.data;
            console.log(`进度: ${taskInfo.progress || 0}%`);
            
            if (taskInfo.state === 1) {
                console.log('视频生成完成:', taskInfo.videos);
                clearInterval(checkStatus);
            } else if (taskInfo.state === -1) {
                console.log('任务失败');
                clearInterval(checkStatus);
            }
        }, 10000);
        
    } catch (error) {
        console.error('请求失败:', error.response?.data || error.message);
    }
}

generateVideo();
```

## cURL 示例

```bash
# 生成视频
curl -X POST "https://your-space-name-your-username.hf.space/videos" \
  -H "X-API-Key: your_moneyprinter_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_subject": "科技创新",
    "video_aspect": "9:16",
    "video_clip_duration": 3,
    "video_source": "pexels",
    "voice_name": "zh-CN-XiaoxiaoNeural"
  }'

# 查询任务状态
curl -X GET "https://your-space-name-your-username.hf.space/tasks/TASK_ID" \
  -H "X-API-Key: your_moneyprinter_api_key"
```

## 错误处理

### 常见错误码

- **401**: API 密钥无效或缺失
- **400**: 请求参数错误
- **404**: 任务不存在
- **500**: 服务器内部错误

### 错误处理示例

```python
def handle_api_response(response):
    if response.status_code == 401:
        print("错误: API 密钥无效，请检查 X-API-Key 头部")
    elif response.status_code == 400:
        print(f"错误: 请求参数错误 - {response.json().get('message', '')}")
    elif response.status_code == 404:
        print("错误: 请求的资源不存在")
    elif response.status_code == 500:
        print("错误: 服务器内部错误，请稍后重试")
    else:
        return response.json()
    return None
```

## 配置说明

### API 密钥获取方式

1. **DeepSeek**: https://platform.deepseek.com/api_keys
2. **Moonshot**: https://platform.moonshot.cn/console/api-keys
3. **Pexels**: https://www.pexels.com/api/
4. **Pixabay**: https://pixabay.com/api/docs/

### 推荐配置

- **LLM**: DeepSeek（国内访问快，价格便宜）
- **视频源**: Pexels（免费，质量高）
- **语音**: Azure TTS V1（免费额度充足）