README.md

---
title: HunyuanVideo-Foley
emoji: 🎵
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: Direct API calling version of HunyuanVideo-Foley model
---

# HunyuanVideo-Foley

<div align="center">
  <h2>🎵 直接 API 调用版本</h2>
  <p><strong>调用官方 tencent/HunyuanVideo-Foley 模型 API</strong></p>
</div>

## 🔗 API 调用模式

这个 Space 通过多种方法直接调用官方 HunyuanVideo-Foley 模型：

### 方法 1: Hugging Face Inference API (推荐)
- ✅ **直接调用**: `tencent/HunyuanVideo-Foley` 官方模型
- 🔑 **需要配置**: `HF_TOKEN` 环境变量  
- 🎵 **最佳质量**: 原始 AI 模型的完整功能

### 方法 2: Gradio Client API  
- 🔄 **备用方案**: 连接到官方 Gradio Space
- 🚀 **无需配置**: 自动尝试连接
- ⚡ **智能切换**: 主 API 失败时启用

### 方法 3: 智能备用方案
- 🎯 **自动启用**: 当所有 API 不可用时
- 🧠 **智能分析**: 根据文本描述生成对应音效
- 🎵 **多种音效**: 脚步声、雨声、风声、车辆声等

## 🚀 使用方法

### ✅ 免配置直接使用
无需任何手动设置，系统自动处理所有 API 调用！

### 使用步骤
1. **上传视频**: 选择要添加音频的视频文件
2. **描述音频**: 用英文描述音效（如 "footsteps on wooden floor"）
3. **调用 API**: 点击生成按钮，系统自动选择最佳 API
4. **获取结果**: 下载生成的高质量音频

## 🎯 支持的音效类型

| 类型 | 示例描述 | 效果 |
|------|----------|------|
| 🚶 **脚步声** | `footsteps on wooden floor` | 木地板脚步声 |
| 🌧️ **自然音** | `rain on leaves` | 雨打叶子声 |
| 💨 **风声** | `wind through trees` | 树林风声 |
| 🚗 **机械音** | `car engine running` | 汽车引擎声 |
| 🚪 **动作音** | `door opening and closing` | 开关门声 |
| 🌊 **水声** | `water flowing in stream` | 溪水流动声 |

## ⚙️ 技术优势

- ✅ **官方模型**: 直接调用腾讯混元官方 API
- 🔄 **智能降级**: 多重备用方案确保服务可用  
- ⚡ **无需本地**: 不需要下载 13GB+ 模型文件
- 🎨 **原始质量**: 保持官方模型的生成质量
- 📱 **易于使用**: 一键调用，自动处理错误

## 🔧 环境配置

### ✅ 无需手动配置
系统自动处理所有 API 调用，无需用户设置任何环境变量！

### 🚀 自动优化
- 自动检测可用的 API 服务
- 智能选择最佳调用方法  
- 确保功能始终可用

## 🎵 API 调用流程

```
1. 用户上传视频 + 文本描述
       ↓
2. 尝试 HF Inference API (优先)
       ↓ (如果失败)
3. 尝试 Gradio Client API  
       ↓ (如果失败)
4. 启用智能备用方案
       ↓
5. 返回生成的音频结果
```

## 📊 API 状态监控

Space 会自动检测和显示：
- ✅ Gradio Client 连接状态
- ✅ HF Inference API 可用性  
- ✅ Replicate API 可用性 (如果配置)

## 🔗 相关链接

- **📂 模型仓库**: [tencent/HunyuanVideo-Foley](https://huggingface.co/tencent/HunyuanVideo-Foley)
- **💻 GitHub**: [Tencent-Hunyuan/HunyuanVideo-Foley](https://github.com/Tencent-Hunyuan/HunyuanVideo-Foley)  
- **📄 论文**: [HunyuanVideo-Foley: Multimodal Diffusion](https://arxiv.org/abs/2508.16930)

## 📝 使用提示

- 🎯 **英文提示**: 推荐使用英文描述以获得最佳效果
- ⏱️ **等待时间**: 首次 API 调用可能需要 1-2 分钟模型加载
- 🔄 **重试机制**: 如果失败会自动尝试其他方法
- 📏 **视频长度**: 建议使用较短视频以提高处理速度

## Citation

```bibtex
@misc{shan2025hunyuanvideofoleymultimodaldiffusionrepresentation,
      title={HunyuanVideo-Foley: Multimodal Diffusion with Representation Alignment for High-Fidelity Foley Audio Generation}, 
      author={Sizhe Shan and Qiulin Li and Yutao Cui and Miles Yang and Yuehai Wang and Qun Yang and Jin Zhou and Zhao Zhong},
      year={2025},
      eprint={2508.16930},
      archivePrefix={arXiv},
      primaryClass={eess.AS}
}
```

## License

This project is licensed under the Apache 2.0 License.

---

<div align="center">
  <p><em>🤖 智能 API 调用版本 | 免配置使用，自动选择最佳 API，确保功能始终可用</em></p>
</div>