- name
- openclaw-plugin-heygen
- display_name
- HeyGen Video Agent
- description
- |
- Covers
- HeyGen v3 Video Agent (api.heygen.com), avatar-presenter video, identity-preserving
- version
- 0.1.2
- homepage
- https://github.com/heygen-com/openclaw-plugin-heygen
- license
- MIT
- metadata
- openclaw
- type
- plugin
- requires
- env
- primaryEnv
- HEYGEN_API_KEY
- registers
- models
- hermes
- tags
- [heygen, avatar, video, presenter, identity, video-agent, openclaw-plugin]
- category
- media
HeyGen Video Agent — OpenClaw Plugin
Adds HeyGen as a first-class provider for OpenClaw's built-in video_generate tool. Same interface every other video provider in OpenClaw uses (Google Veo, Runway, Kling, Wan, MiniMax, Dashscope) — now with identity-preserving avatar/presenter video.
Install
openclaw plugin install heygenSet HEYGEN_API_KEY in your environment (get one at <https://app.heygen.com/settings/api>).
Quick start
const result = await video_generate({
model: "heygen/video_agent_v3",
prompt: "Hi team, here's the product update for this week.",
providerOptions: {
avatar_id: "<your-avatar-id>",
voice_id: "<your-voice-id>",
orientation: "landscape", // or "portrait"
},
});
// result.url → downloadable .mp4Avatar / voice ids: list from the HeyGen dashboard or the heygen-skills companion skill (which composes opinionated avatar/voice picking on top of this plugin).
When HeyGen vs other video providers
- Avatar-presenter / talking-head video → HeyGen.
- Cinematic / scene generation → Veo, Runway, Kling.
- Translation / dubbing → use HeyGen's translate APIs (separate skill).
- Real-time interactive avatar → HeyGen Streaming Avatar (separate surface, not this plugin).
Provider options
| Field | Type | Notes | |
|---|---|---|---|
avatar_id | string | HeyGen avatar id; falls back to models.providers.heygen.defaultAvatarId. | |
voice_id | string | HeyGen voice id; falls back to models.providers.heygen.defaultVoiceId. | |
style_id | string | Optional style template. | |
orientation | `"landscape" \ | "portrait"` | Maps from aspect ratio. 1:1 rejected. |
mode | `"generate" \ | "chat"` | Default generate. chat keeps full poll budget for interactive flows. |
callback_url | string | Async webhook completion. | |
callback_id | string | Caller-supplied correlation id for the webhook. | |
incognito_mode | boolean | Skip retention on HeyGen side where supported. |
Errors surfaced cleanly
401→HeyGen API key missing or invalid402/ quota →HeyGen credit limit reached- Generate-mode + 8 consecutive
thinkingpolls → fast-fail with a hint pointing atavatar_id/voice_id. failedstatus surfaces HeyGen'sfailure_messagerather than a generic error.
Polling
Three-tier backoff: 5s × 6 → 15s × 12 → 30s until MAX_POLL_ATTEMPTS. Long renders (20–45 min) stay under typical HeyGen per-key rate limits.
Source + tests
- Repo: <https://github.com/heygen-com/openclaw-plugin-heygen>
- 19 unit tests, live smoke verified end-to-end against
api.heygen.com. - Extracted from openclaw/openclaw#69578 (closed in favor of external/ClawHub publication per VISION.md).
License
MIT. See LICENSE.