HeyGen视频批量生成指南：利用API实现数字人自动化制作

批量生成HeyGen数字人视频，需要借助其最新的RESTful API来实现。目前主要有四种实用的技术路径：一是通过循环调用/v1/videos接口；二是配置Webhook异步接收完成通知；三是结合curl、jq和Shell脚本构建命令行工具；四是利用Python多线程并发提交任务。

如果您希望大批量生成HeyGen数字人视频，而不是依赖网页端逐个手动操作，那么就需要通过HeyGen官方提供的RESTful API进行程序化调用。本文将详细介绍实现这一目标的多种技术方案。

一、调用HeyGen最新API创建批量任务

HeyGen提供了/v1/videos接口，用于提交视频生成请求。该接口支持通过JSON载荷定义脚本、头像、语音、背景等多种参数。需要注意的是，每次请求仅生成一个视频，批量处理需要在客户端通过循环构造并发起多个独立请求。

1. 首先，前往HeyGen开发者后台申请API Key，并确保您的账户已启用API访问权限。

2. 构造一个包含scene_script、avatar_id、voice_id等字段的POST请求体。请确保脚本文本长度不超过5000字符，并且符合HeyGen的内容政策。

3. 在HTTP头信息中设置Authorization为Bearer your_api_key_here，并将Content-Type设为application/json。

4. 对于每个待生成的视频，建议使用唯一的client_video_id字段进行标识，以便后续轮询状态或归档结果。

5. 使用for循环或队列机制依次发送请求。请注意，相邻请求之间应保持至少1.5秒的间隔，以避免触发速率限制（默认为每分钟10次）。

二、基于Webhook实现异步结果接收与聚合

HeyGen支持在视频生成完成时，向您指定的URL推送通知。这可以替代频繁轮询GET /v1/videos/{video_id}接口的方式，有效降低请求开销并提升系统响应的实时性。

1. 部署一个具备公网可访问地址的HTTP服务端点，例如 https://yourdomain.com/webhook/heygen。

2. 在HeyGen开发者控制台中配置Webhook URL，并勾选video.completed事件类型。

3. 当HeyGen向您的端点推送POST请求时，解析其payload中的video_id与status字段。确认status为completed后，调用GET /v1/videos/{video_id}/download_url获取视频直链。

4. 将下载链接与原始任务元数据（如输入文案、时间戳、批次ID等）写入本地数据库或CSV文件，形成结构化的批次记录。

5. 对同一批次下的全部video.completed通知完成收集后，触发归档压缩或FTP上传等后续动作。

三、使用CLI工具配合Shell脚本编排任务

虽然HeyGen尚未发布官方的命令行工具，但我们完全可以通过curl、jq和bash的组合，快速构建一个轻量级的命令行批量处理工具，它尤其适用于Linux或macOS环境下的定时批量任务。

1. 编写Shell脚本，读取CSV文件中的每一行数据，提取出script_text、avatar_name、voice_name等字段。

2. 调用jq动态生成JSON请求体。其中，avatar_id可通过预先查询并缓存GET /v1/avatars?name=${avatar_name}接口的映射关系来获取。

3. 执行核心命令：curl -X POST “https://api.heygen.com/v1/videos“ -H “Authorization: Bearer ${KEY}“ -d “@request.json” > response.json。

4. 从response.json文件中提取id字段，将其与时间戳、脚本哈希等信息一同写入task_queue.txt队列文件，格式建议为 id,timestamp,script_hash。

5. 另起一个守护进程，每30秒扫描一次task_queue.txt，对其中未完成的id调用GET /v1/videos/${id}接口。当status返回processing或completed时，记录日志并将其移出队列。

四、集成Python脚本实现多线程并发提交

利用requests.Session和concurrent.futures.ThreadPoolExecutor，我们可以在单机上安全地提升API吞吐量，同时规避全局速率限制可能带来的排队延迟。

1. 初始化Session对象以实现连接复用，并在default headers中设置好Authorization和Content-Type。

2. 准备视频参数列表videos_config。列表中的每个元素为一个字典，包含script、avatar_id、voice_id、background等必要键值。

3. 定义submit_single_video函数。在函数内部，注意捕获requests.exceptions.RequestException。任务失败时，记录相应的错误码与重试次数。

4. 使用ThreadPoolExecutor(max_workers=3)提交全部任务。请注意，max_workers值须严格≤3，以满足HeyGen当前的并发限制要求。

5. 将成功返回的video_id与对应的配置索引号存入results列表。最终，统一将其导出为JSONL格式文件，每行记录格式为{video_id, config_index, submitted_at}。