使用Python脚本自动调用HeyGem API进行无人值守生成-开发者社区

使用Python脚本自动调用HeyGem API进行无人值守生成

在AI内容创作日益普及的今天，企业对高效、低成本的视频生产能力提出了更高要求。尤其是在在线教育、品牌宣传和虚拟主播等场景中，需要频繁将音频内容与数字人形象结合生成口型同步的视频。传统的手动操作方式不仅耗时费力，还难以应对批量任务的需求。

HeyGem 作为一款基于AI的数字人视频生成系统，提供了直观的Web界面用于合成高质量的口型驱动视频。然而，其默认设计仍依赖人工交互——上传音频、选择模板、点击生成……这一系列动作若每天重复数十次，显然无法满足自动化生产的需求。有没有办法让整个流程“自己跑起来”？

答案是肯定的：即使没有官方API文档，我们依然可以通过逆向分析其前端请求，用Python脚本实现全自动化的任务提交与结果获取。

背后的技术逻辑并不复杂

HeyGem 的服务底层使用的是 Gradio 框架构建的 Web 应用，运行在http://localhost:7860（或远程服务器IP）。你所看到的每一个按钮、输入框和下拉菜单，在背后其实都是一个可被HTTP请求触发的功能模块。当你在界面上点击“开始批量生成”时，浏览器会向/run/predict发起 POST 请求，携带所有参数和文件数据。

这意味着，只要我们能模拟出相同结构的请求，就可以绕过浏览器直接与后端通信。这正是自动化调用的核心思路——把人的操作转化为机器可执行的网络请求。

Gradio 的接口虽然不像标准 RESTful API 那样清晰命名，但它遵循一种固定的模式：

所有功能调用都走/run/predict
参数以 JSON 数组形式传递，顺序对应前端组件索引
文件通过multipart/form-data上传
返回结果包含生成路径或状态信息

因此，关键不在于是否有公开文档，而在于能否准确还原请求格式。

如何抓取并复现真实请求？

第一步是在浏览器中打开开发者工具（F12），切换到 Network 面板，然后在 HeyGem 界面执行一次完整的批量生成操作。你会看到一条对/run/predict的 XHR 请求。点击查看详情：

Headers中复制Content-Type、Referer和其他必要头信息；
Payload里可以看到data字段是一个数组，元素顺序严格对应UI组件；
fn_index表示当前调用的是哪个功能函数（不同标签页/按钮值不同）；
上传的文件出现在 Form Data 区域，类型为application/octet-stream。

有了这些信息，就能在 Python 中构造出几乎一模一样的请求。唯一需要注意的是：组件顺序必须完全一致。比如第一个是音频输入框，第二个是视频列表，第三个是“清空历史”的复选框，那么你的data数组就必须按这个顺序填入值，哪怕某些字段为空也要占位（用None）。

此外，session_hash是 Gradio 用来标识会话的随机字符串，每次请求建议生成一个新的（例如用时间戳哈希），避免冲突。

自动化脚本的设计要点

下面是一段经过实战验证的 Python 实现，它封装了从任务提交到结果处理的全流程：

import requests import time import os from pathlib import Path class HeyGemAutomator: def __init__(self, base_url="http://localhost:7860"): self.base_url = base_url.rstrip("/") self.session = requests.Session() self.headers = { "User-Agent": "Mozilla/5.0", "Referer": f"{self.base_url}/" } def batch_generate(self, audio_path: str, video_paths: list, timeout=300): url = f"{self.base_url}/run/predict" files = [] # 上传音频文件 audio_file = open(audio_path, 'rb') files.append(("files", (os.path.basename(audio_path), audio_file, "audio/wav"))) # 逐个上传视频文件 for vid in video_paths: vf = open(vid, 'rb') files.append(("files", (os.path.basename(vid), vf, "video/mp4"))) # 注意：data中的顺序必须与前端组件一致！ data = { "data": [ None, # 占位：音频（已在files中） None, # 占位：视频列表 False # 是否清空历史记录 ], "fn_index": 0, "session_hash": str(int(time.time())) } try: print(f"正在提交任务... 音频={audio_path}, 视频数量={len(video_paths)}") response = self.session.post( url, data={"data": data["data"], "fn_index": data["fn_index"]}, files=files, headers=self.headers, timeout=timeout ) if response.status_code == 200: result = response.json() return { "success": True, "output": result.get("data", []), "message": "任务已成功提交" } else: return { "success": False, "error": f"HTTP {response.status_code}", "details": response.text } except Exception as e: return { "success": False, "error": "请求失败", "exception": str(e) } finally: audio_file.close() for _ in video_paths: try: locals()['vf'].close() # 确保文件句柄释放 except: pass def download_results(self, output_dir="./outputs"): print(f"💡 建议检查服务器上的 outputs 目录获取最新视频") Path(output_dir).mkdir(exist_ok=True)

这段代码有几个值得强调的工程细节：

使用requests.Session()保持连接复用，提升多任务连续提交的效率；
对每个打开的文件都做了显式关闭处理，防止资源泄露；
加入了异常捕获和超时控制，适合长时间运行的任务调度；
fn_index和data的结构需根据实际界面调试确认——最可靠的方式是抓包比对。

在真实业务中如何落地？

设想这样一个典型工作流：市场部门每天要发布10条短视频，内容由同一段配音配上不同的数字人形象。过去需要专人登录系统逐一上传，现在只需一个脚本定时扫描指定目录即可完成全部提交。

更进一步，你可以将其嵌入更大的内容生产流水线：

[数据库/消息队列] ↓ [Python调度脚本] → [调用HeyGem API] ↓ ↓ [日志记录 & 状态追踪] [视频输出至 /outputs] ↓ ↓ [微信通知/邮件提醒] ← [监听新文件生成]

具体步骤如下：

启动服务：确保bash start_app.sh已运行，服务监听在7860端口；
准备素材：将待处理的音频和视频放入固定目录；
触发脚本：可通过 cron 定时执行，或由上游系统推送事件触发；
监控进度：轮询outputs目录判断是否生成完毕（也可解析日志判断）；
后续动作：视频生成后自动上传至CDN、归档至S3、发送通知等。

举个例子，用 Linux 的cron设置夜间任务：

# 每晚2点执行批量生成 0 2 * * * /usr/bin/python3 /root/scripts/heygem_auto.py

这样既能避开白天的高负载时段，又能保证第二天一早就有成品可用。

常见问题与优化策略

1. 组件顺序错乱导致失败

这是最常见的错误来源。Gradio 的data数组必须严格按照前端组件顺序填充。解决方法：
- 抓包对比原始请求体；
- 或尝试逐步调整data长度和值类型，观察返回变化。

2. 大文件上传超时

建议设置合理的timeout参数（如300秒），并在网络不稳定环境下加入重试机制：

from tenacity import retry, stop_after_attempt, wait_fixed @retry(stop=stop_after_attempt(3), wait=wait_fixed(2)) def safe_batch_generate(...): ...

3. 并发访问引发资源竞争

多个脚本同时调用可能导致GPU内存溢出。推荐做法：
- 使用文件锁或Redis分布式锁控制并发；
- 或采用串行队列方式依次处理任务。

4. 缺乏实时状态反馈

目前/run/predict只返回初始响应，无法知道何时真正完成。改进方向：
- 监听日志文件：tail -f /root/workspace/运行实时日志.log；
- 或扩展HeyGem服务，添加/status接口返回当前队列状态。

5. 安全性考虑

若将服务暴露在公网，务必添加认证层：
- 通过 Nginx 添加 Basic Auth；
- 或集成 OAuth2 代理，限制访问权限。

为什么这种方式仍然有价值？

尽管 HeyGem 没有提供官方 API，但这种“逆向调用 + 脚本封装”的模式，在实际工程中极具生命力。它体现了一种典型的“低代码+高自动化”思维：不等待完美接口，而是利用现有能力快速构建解决方案。

更重要的是，这种方法具备良好的可扩展性。一旦验证可行，就可以轻松接入 Airflow、Celery 或 Jenkins 等成熟调度系统，实现：

任务优先级管理
失败自动重试
执行日志审计
性能监控告警

最终形成一个稳定可靠的“AI内容工厂”。

写在最后

本文展示的不仅是如何调用一个隐藏接口，更是一种面对封闭系统的破局思路：当工具不具备你想用的方式时，就让它适应你的流程。

通过短短几十行 Python 代码，我们将原本需要数小时的人工操作压缩到几分钟内自动完成。这种转变带来的不只是效率提升，更是思维方式的升级——从“我该怎么点下一步”，转变为“这个流程能不能自己跑完”。

未来，随着更多AI应用进入企业环境，类似的自动化需求只会越来越多。掌握这类“非标集成”能力，将成为工程师的一项核心竞争力。

而这套方法论也适用于其他基于 Gradio、Streamlit 等框架构建的应用：只要能抓到请求，就能实现自动化。真正的瓶颈从来不是技术本身，而是我们是否愿意多走一步，去揭开那层看似不可触碰的黑盒。

使用Python脚本自动调用HeyGem API进行无人值守生成