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#

bash

openclaw plugin install heygen

Set HEYGEN_API_KEY in your environment (get one at https://app.heygen.com/settings/api).

Quick start#

ts

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 .mp4

Avatar / 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#

FieldTypeNotesavatar_idstringHeyGen avatar id; falls back to models.providers.heygen.defaultAvatarId.voice_idstringHeyGen voice id; falls back to models.providers.heygen.defaultVoiceId.style_idstringOptional 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_urlstringAsync webhook completion.callback_idstringCaller-supplied correlation id for the webhook.incognito_modebooleanSkip retention on HeyGen side where supported.

Errors surfaced cleanly#

• 401 → HeyGen API key missing or invalid
• 402 / quota → HeyGen credit limit reached
• Generate-mode + 8 consecutive thinking polls → fast-fail with a hint pointing at avatar_id / voice_id.
• failed status surfaces HeyGen's failure_message rather 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.