# Assets Source: https://developers.heygen.com/assets Upload files for use across the HeyGen API. Upload images, videos, audio, or PDFs to get an `asset_id` you can reference in other endpoints — like `POST /v3/video-agents`, `POST /v3/videos`, or `POST /v3/avatars`. ## Upload an Asset ```bash theme={null} curl -X POST https://api.heygen.com/v3/assets \ -H "x-api-key: YOUR_API_KEY" \ -F "file=@./my-photo.png" ``` ```json Response theme={null} { "data": { "asset_id": "ast_abc123", "url": "https://files.heygen.com/asset/ast_abc123.png", "mime_type": "image/png", "size_bytes": 204800 } } ``` ## Supported File Types | Category | Formats | | -------- | --------- | | Image | PNG, JPEG | | Video | MP4, WebM | | Audio | MP3, WAV | | Document | PDF | Max file size: **32 MB**. MIME type is auto-detected from file bytes. ## Using Assets Once uploaded, reference the `asset_id` anywhere the API accepts asset inputs: ```json theme={null} // In POST /v3/video-agents (file attachments) { "prompt": "Explain this diagram", "files": [{ "type": "asset_id", "asset_id": "ast_abc123" }] } ``` ```json theme={null} // In POST /v3/avatars (photo avatar) { "type": "photo", "name": "My Avatar", "file": { "type": "asset_id", "asset_id": "ast_abc123" } } ``` Anywhere that accepts an asset also accepts a direct URL (`{"type": "url", "url": "https://..."}`) or base64 (`{"type": "base64", "media_type": "image/png", "data": "..."}`). Use `asset_id` when you need to reuse the same file across multiple requests. # Automated Broadcast Source: https://developers.heygen.com/automated-broadcast Build a pipeline that generates and distributes video content on a schedule — daily news, weekly updates, recurring series. ## The Problem Publishing regular video content — daily news roundups, weekly company updates, recurring educational series — is unsustainable without a production team. But consistency is what builds an audience. ## How It Works ``` Schedule triggers → Aggregate content → LLM writes script → Video Agent renders → Auto-distribute ``` A fully automated pipeline that runs on a schedule, collects fresh content from your sources, generates a video, and delivers it to your audience — no human in the loop. ## Build It Pull content from whatever sources feed your broadcast. ```python theme={null} import requests from datetime import datetime def aggregate_content(): stories = [] # RSS feeds import feedparser feed = feedparser.parse("https://news.ycombinator.com/rss") for entry in feed.entries[:5]: stories.append({ "title": entry.title, "summary": entry.get("summary", ""), "source": "Hacker News", "url": entry.link, }) # APIs (example: your internal metrics) metrics = requests.get("https://api.yourapp.com/weekly-stats").json() stories.append({ "title": f"This week: {metrics['new_users']} new users, {metrics['revenue']} revenue", "summary": f"Growth of {metrics['growth_pct']}% week over week", "source": "Internal", }) return stories stories = aggregate_content() ``` ```python theme={null} import anthropic client = anthropic.Anthropic() story_text = "\n".join( f"- {s['title']} ({s['source']}): {s['summary']}" for s in stories ) message = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=1500, messages=[{ "role": "user", "content": f"""Create a HeyGen Video Agent prompt for a 60-second news/update video. Date: {datetime.now().strftime('%B %d, %Y')} Stories to cover: {story_text} Structure: - Intro (5s): "Here's your [daily/weekly] update for [date]" - Stories (45s): Cover the top 3 stories with text overlays for key stats - Sign-off (10s): "That's your update. See you [tomorrow/next week]." Tone: Authoritative but approachable. Clean, news-desk style background. Keep pacing brisk — one story every 15 seconds.""" }], ) video_prompt = message.content[0].text ``` ```python theme={null} resp = requests.post( "https://api.heygen.com/v3/video-agents", headers={ "X-Api-Key": HEYGEN_API_KEY, "Content-Type": "application/json", }, json={"prompt": video_prompt}, ) video_id = resp.json()["data"]["video_id"] # Poll until complete import time while True: status = requests.get( f"https://api.heygen.com/v3/videos/{video_id}", headers={"X-Api-Key": HEYGEN_API_KEY}, ).json()["data"] if status["status"] == "completed": video_url = status["video_url"] break elif status["status"] == "failed": raise Exception(f"Video failed: {status.get('failure_message')}") time.sleep(15) ``` Deliver the video to your audience wherever they are. ```python theme={null} # Telegram import telegram bot = telegram.Bot(token=TELEGRAM_TOKEN) bot.send_video(chat_id=CHANNEL_ID, video=video_url, caption="Daily Update") # Slack requests.post(SLACK_WEBHOOK, json={ "text": f"Daily update is ready: {video_url}", }) # Email (via your ESP) send_email( to=subscriber_list, subject=f"Your Daily Update — {datetime.now().strftime('%B %d')}", html=f'', ) ``` Run the pipeline on a schedule using cron, GitHub Actions, or a cloud function. ```yaml theme={null} # .github/workflows/daily-broadcast.yml name: Daily Video Broadcast on: schedule: - cron: '0 17 * * 1-5' # 5 PM UTC, weekdays jobs: broadcast: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: pip install -r requirements.txt - run: python broadcast.py env: HEYGEN_API_KEY: ${{ secrets.HEYGEN_API_KEY }} ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }} ``` ## Real-World Example STUDIO 47, a German broadcaster, reported these results after adopting HeyGen for automated video production (via [HeyGen customer stories](https://www.heygen.com/customer-stories/studio-47)): * Significantly faster content creation * 24/7 production capability * Substantial cost reduction vs traditional production * Expanded into multilingual content that wasn't feasible before ## Resilient Delivery Build fallbacks for when things go wrong: ```python theme={null} def deliver(video_url, caption): try: # Try primary: send video by URL bot.send_video(chat_id=CHANNEL_ID, video=video_url, caption=caption) except Exception: try: # Fallback: download and upload as file video_data = requests.get(video_url).content bot.send_video(chat_id=CHANNEL_ID, video=video_data, caption=caption) except Exception: # Last resort: send text with link bot.send_message(chat_id=CHANNEL_ID, text=f"{caption}\n\n{video_url}") ``` ## Broadcast Types | Type | Schedule | Content source | Duration | | --------------------- | -------------- | -------------------------------- | -------- | | **Daily news** | Every morning | RSS, APIs, web scrape | 45–60s | | **Weekly roundup** | Monday morning | Internal metrics + industry news | 90s | | **Product changelog** | Each release | Git commits, release notes | 30–45s | | **Company all-hands** | Weekly/monthly | Meeting notes, updates | 60–90s | | **Social digest** | Daily | Trending topics in your niche | 30s | ## Variations * **Multi-language:** Generate once, [translate](/cookbook/video-agent/multilingual-content) for regional audiences * **Different avatars per topic:** Use different presenters for different content categories * **Audience segmentation:** Generate different versions for different subscriber segments *** ## Next Steps Repurpose existing content instead of aggregating new content. Trigger video generation from code changes instead of a schedule. # Automated Video Pipeline Source: https://developers.heygen.com/automated-pipeline Generate videos programmatically from data — in CI/CD, on a schedule, or triggered by events. ## The Problem You need to generate the same type of video repeatedly with different data — weekly reports, personalized onboarding videos, per-customer dashboards, changelog announcements. Doing this manually doesn't scale. ## How It Works ``` Data event → Template composition + injected data → Hyperframes render → Distribute ``` Hyperframes compositions are just HTML files. You can template them, inject data, and render programmatically — no browser, no human, no AI agent in the loop. ## Build It Build one great composition with your AI agent, then extract the variable parts: ```html theme={null}
{{ACTIVE_USERS}} active users this week
{{REVENUE}} revenue
``` ```python theme={null} import subprocess import shutil from pathlib import Path def generate_report_video(data: dict, output_path: str): """Generate a weekly report video from data.""" # Copy template work_dir = Path(f"/tmp/report-{data['week']}") shutil.copytree("templates/weekly-report", work_dir, dirs_exist_ok=True) # Inject data into template html = (work_dir / "index.html").read_text() html = html.replace("{{ACTIVE_USERS}}", f"{data['active_users']:,}") html = html.replace("{{REVENUE}}", f"${data['revenue']:,.0f}") html = html.replace("{{GROWTH}}", f"{data['growth_pct']:.1f}%") (work_dir / "index.html").write_text(html) # Render subprocess.run([ "npx", "hyperframes", "render", "--output", output_path, "--quality", "standard", "--fps", "30", ], cwd=str(work_dir), check=True) # Cleanup shutil.rmtree(work_dir) return output_path ``` **GitHub Actions:** ```yaml theme={null} # .github/workflows/weekly-report.yml name: Weekly Report Video on: schedule: - cron: '0 9 * * 1' # Every Monday at 9am jobs: generate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '22' - run: sudo apt-get install -y ffmpeg - run: python scripts/generate_report.py - uses: actions/upload-artifact@v4 with: name: weekly-report path: renders/*.mp4 ``` **Webhook-triggered:** ```python theme={null} from flask import Flask, request app = Flask(__name__) @app.route("/webhook/new-signup", methods=["POST"]) def on_new_signup(): user = request.json generate_welcome_video( name=user["name"], company=user["company"], output=f"renders/welcome-{user['id']}.mp4" ) # Upload to CDN, send via email, etc. return {"status": "ok"} ``` ## Pipeline Patterns | Trigger | Data source | Output | Example | | ----------------- | ---------------------- | --------------------------- | ------------------------- | | **Cron schedule** | Database query | Weekly/monthly report video | Monday metrics recap | | **Webhook** | Event payload | Per-user personalized video | Welcome onboarding | | **Git push** | Changelog / commit log | Release announcement | "What's new in v2.4" | | **API call** | Request parameters | On-demand custom video | Customer dashboard export | ## Combine with Video Agent For the best of both worlds — motion graphics + avatar narration: ```python theme={null} def generate_narrated_report(data): # Step 1: Render the motion graphics with Hyperframes graphics_path = generate_report_video(data, "renders/graphics.mp4") # Step 2: Generate avatar narration with Video Agent narration = requests.post( "https://api.heygen.com/v3/video-agents", headers={"X-Api-Key": HEYGEN_API_KEY}, json={ "prompt": f"""Narrate this weekly report: {data['active_users']:,} active users (up {data['growth_pct']:.0f}%), ${data['revenue']:,.0f} revenue. Keep it under 15 seconds, upbeat and concise.""", }, ).json() # Step 3: Composite in Hyperframes (avatar PiP over graphics) # ... or use ffmpeg to overlay ``` Start simple — get one template working end-to-end, then add automation. A working pipeline that generates one video type reliably is more valuable than a complex system that handles everything. *** ## Next Steps Build the animated visualizations that feed into your pipeline. Similar automation pattern using Video Agent for avatar-based content. # Changelog Source: https://developers.heygen.com/changelog Product updates and announcements for the HeyGen API and developer platform. **Video engine updates and new brand kit integration** We have updated the video generation workflow and introduced support for Brand Kits across Video Agents. Note that the `engine` parameter structure for `POST /v3/videos` has changed, which is a breaking change for existing integrations. * **Breaking Change:** The `engine` property in `POST /v3/videos` now requires an object structure (e.g., `{"type": "avatar_v"}`) instead of a string. `ApiAvatarEngine` has been removed. * **Video Scaling:** Added a new optional `fit` parameter to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request types. * **Brand Kits:** Added `brand_kit_id` as an optional parameter to `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}`. * **New Endpoint:** Added `GET /v3/brand-kits` to retrieve available brand kit resources. * **Parameter Constraints:** Note that `expressiveness` and `motion_prompt` in `POST /v3/videos` are now strictly for Avatar IV and are not supported when `engine.type` is set to `avatar_v`. **New configuration options for Video Translation and Video Generation** We have introduced support for Stock TTS in video translations and added explicit engine selection for avatar-based video generation. * **Video Translation:** Added `stock_voice_config` to `POST /v2/video_translate` and `POST /v3/video-translations`. This allows users to opt into Stock TTS instead of using Voice Cloning. * **Video Generation:** Added an optional `engine` field to `POST /v3/videos` (for `CreateVideoFromAvatar` requests). You can now explicitly select between Avatar IV and Avatar V engines. If omitted, the system defaults to Avatar IV. **Updated schema definitions for Avatar engine support** Metadata for supported API engines has been updated across the avatar look endpoints to ensure consistency when retrieving avatar configurations. * Updated `supported_api_engines` fields in: * `POST /v3/avatars` * `GET /v3/avatars/looks` * `GET /v3/avatars/looks/{look_id}` * `PATCH /v3/avatars/looks/{look_id}` **Fine-tune watermark size, transparency, and position** The `watermark` object on `POST /v3/videos` now accepts three new optional fields for finer control over how your watermark renders: * `scale` (number, `0`–`2`, default `1.0`) — adjust the watermark size relative to its native resolution. * `opacity` (number, `0`–`1`, default `1.0`) — control transparency. * `placement` — choose an anchor corner (`top_left`, `top_right`, `bottom_left`, `bottom_right`) and apply fractional `offset_x` / `offset_y` values for precise positioning. All fields are optional and backward-compatible. Omitting them preserves the existing bottom-right default behavior. **Programmatic voice cloning is now available** You can now create and manage voice clones directly from the API, no dashboard step required. * `POST /v3/voices/clone` initiates a clone from a reference audio sample. * `GET /v3/voices/{voice_id}` returns clone status and details so you can poll until processing completes. * Use the resulting `voice_id` anywhere a voice is accepted (`POST /v3/videos`, `POST /v3/voices/speech`, etc.). See the [voices overview](/docs/voices/overview) for details. **Render captions directly into your videos** `POST /v2/videos` and `POST /v3/videos` now accept a `caption.style` field. Set it to burn captions into the rendered video instead of (or in addition to) consuming the sidecar subtitle file at `subtitle_url`. Useful for social platforms where viewers watch with sound off and you want captions baked into the asset. **Apply your own watermark to generated videos** `POST /v3/videos` accepts a new optional `watermark` property on both `CreateVideoFromAvatar` and `CreateVideoFromImage` requests. Pass a PNG or JPEG image to overlay it onto the rendered output — handy for branding, attribution, or moderation marks. Available as a premium option for select Enterprise customers — [contact support](https://help.heygen.com) to request access. **`watermark` now uses the `WatermarkInput` schema** The inline schema previously used for the `watermark` field on video generation requests has been replaced with the dedicated `WatermarkInput` type. The shape of the property has changed — update existing payloads to match the new schema before upgrading. **Empty `title` queries are no longer accepted** `GET /v2/videos` and `GET /v3/videos` now require at least one character for the `title` query parameter (`minLength` increased from 0 to 1). Omit the parameter entirely if you don't want to filter by title — sending an empty string will return a validation error. **Better error feedback when the voice clone limit is reached** `POST /v3/voices/clone` now returns the `resource_limit_reached` error code (HTTP 400) when your account has hit its voice clone quota, instead of a generic validation error. The response message tells you to delete unused clones or contact support to raise the limit. See the [error codes reference](/docs/error-codes#resource-limit-reached) for handling guidance. **Expanded tool coverage for the HeyGen MCP server** The HeyGen Remote MCP server now includes tools for managing avatars, videos, lipsync, and video translation — making more of the API accessible to AI agents like Claude, Cursor, Gemini CLI, and Manus. * Added avatar management tools: `create_digital_twin`, `create_photo_avatar`, `create_prompt_avatar`, `create_avatar_consent`, `list_avatar_looks`, `get_avatar_look`, `update_avatar_look`, and more. * Added full video CRUD: `create_video_from_avatar`, `create_video_from_image`, `list_videos`, `get_video`, `delete_video`. * Added lipsync and video translation management tools. * Added `design_voice` for finding voices from a natural-language description. * See the [MCP overview](/mcp/overview) for the full tool list. **CLI command surface synced with v3 API** The HeyGen CLI now covers all v3 endpoints, including Video Agent, Lipsync, Video Translation (with Proofreads), Webhooks, and Assets. * Added `--wait` flag for blocking until async operations complete, with configurable `--timeout`. * Added `--request-schema` and `--response-schema` flags to inspect API schemas without authentication. * Added `--force` flag for non-interactive destructive operations in CI. * See the [CLI commands](/commands) and [features](/features) pages for usage details. **v1 and v2 endpoints sunset on October 31, 2026** A formal deprecation timeline is now in place for the v1 and v2 API. Both versions remain fully operational through October 31, 2026, after which they will be retired. * Studio API (multi-scene) and Template API will continue to be supported on v2 until a v3 equivalent is available. * See the [endpoint version comparison](/endpoint-version-comparison) for a full migration checklist and feature comparison. **More granular error responses across the API** New error codes provide clearer feedback when requests fail, making it easier to handle edge cases in your integration. * `ai_vendor_access_restricted` — workspace AI vendor policy blocks the request. * `unlimited_mode_disabled` — avatar doesn't support unlimited mode. * `voice_unavailable` — cloned voice failed processing or expired. * `ephemeral_upload_disabled` — eager upload temporarily disabled for the account. * `gateway_timeout` — external resource could not be fetched in time. * See the full [error codes reference](/docs/error-codes) for details and troubleshooting. **New requirement for Starfish engine compatibility** Text-to-speech generation endpoints now require the use of voices that support the Starfish engine. * Updated `POST /v1/audio/text_to_speech` and `POST /v3/voices/speech` documentation. * Developers should filter for compatible voices by passing `engine=starfish` when calling the voice listing endpoints. **Standardized Asset ID descriptions** Documentation across multiple endpoints has been clarified to consistently refer to asset IDs originating from the HeyGen asset upload endpoint. No functional changes were made to the API behavior. * Applies to request bodies for: * `POST /v3/avatars` * `POST /v3/lipsyncs` * `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}` * `POST /v3/video-translations`, `POST /v3/video-translations/proofreads`, and `PUT /v3/video-translations/proofreads/{proofread_id}/srt` * `POST /v3/videos` **New endpoint for listing Video Agents** We have introduced a new endpoint to allow developers to retrieve a list of all existing video agents associated with their account. * Added `GET /v3/video-agents`: Use this endpoint to fetch your video agents, enabling easier integration and management of your agent instances. **Updated error codes for Avatar endpoints** We have updated the error response codes for avatar-related endpoints to provide more specific feedback when a group cannot be located. * `GET /v3/avatars/{group_id}`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`. * `POST /v3/avatars/{group_id}/consent`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`. **Advanced voice customization and output formatting** We have introduced new parameters to provide finer control over generated audio and video output quality. * Added `volume` and `engine_settings` to `voice_settings` for `POST /v2/videos` and `POST /v3/videos`. These settings apply when using text-to-speech (`script` + `voice_id`). * Added `output_format` to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request schemas. **Improved error handling for webhook management** We have updated our webhook endpoints to provide more consistent and descriptive error responses. * Added a `409` conflict response to `POST /v3/webhooks/endpoints` to better handle registration errors. * Standardized error codes for `404` responses across `DELETE`, `PATCH`, and `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret` by updating the error code to `webhook_not_found`. **Support for custom output formats in video generation** You can now specify a preferred output format when creating videos. The API response now includes the `output_format` field to confirm the format used for your generated video. * Added optional `output_format` request property to `POST /v2/videos`. * Added `output_format` to the response body of `POST /v2/videos` (200 OK). * Added `output_format` to the response body of `POST /v3/videos` (200 OK). **Comprehensive API Documentation Updates** We have updated the endpoint descriptions across our entire V3 API to provide clearer guidance, better parameter context, and more precise functionality definitions. While the underlying API logic remains consistent, the improved documentation clarifies how to integrate with our latest engine versions and features. * **Video Generation**: `POST /v3/videos` now officially documents support for the Avatar IV engine and upcoming Avatar V. * **Avatars**: Clarified workflows for `POST /v3/avatars` (asynchronous training) and added guidance on the mandatory consent flow for private avatars via `POST /v3/avatars/{group_id}/consent`. * **Video Agent**: Streamlined descriptions for session-based interactions, clearly distinguishing between `generate` (one-shot) and `chat` (multi-turn) modes. * **Lipsync & Translation**: Updated documentation for `POST /v3/lipsyncs` and `POST /v3/video-translations` to emphasize the `speed` vs. `precision` mode selection for output quality. * **Webhooks**: Clarified that `PATCH /v3/webhooks/endpoints/{endpoint_id}` performs a full replacement of the event types array. * **Assets**: Updated supported MIME types for `POST /v3/assets` to include refined file type lists. **Added caption\_url to Lipsync and Video Translation responses** You can now retrieve the `caption_url` for generated lipsyncs and video translations, providing direct access to the generated caption files. * `GET /v3/lipsyncs` and `GET /v3/lipsyncs/{lipsync_id}` * `PATCH /v3/lipsyncs/{lipsync_id}` * `GET /v3/video-translations` and `GET /v3/video-translations/{video_translation_id}` * `PATCH /v3/video-translations/{video_translation_id}` **Updated documentation for avatar consent** Clarified the implementation details for the avatar consent flow to ensure a smoother user experience. * `POST /v3/avatars/{group_id}/consent`: Updated documentation to clarify that the returned URL must be presented directly to the user in a browser to complete the consent process. **Support for avatar-default voices** You can now generate videos using an avatar's default voice without explicitly specifying a `voice_id`. When creating a video, if `voice_id` is omitted while `avatar_id` is present, the system will automatically use the avatar's default voice. * Updated `POST /v3/videos`: The `voice_id` requirement has been relaxed for both `CreateVideoFromAvatar` and `CreateVideoFromImage` schemas, allowing the system to fall back to the avatar's default voice. **Enhanced capabilities for Video Agent interactions** We have updated the description and scope of the `POST /v3/video-agents/{session_id}` endpoint to better reflect its versatility in managing agent-led workflows. * Updated the endpoint description to clarify support for answering agent-posed questions and requesting specific edits or revisions. * The request body schema has been updated to better align with these extended conversational and editing capabilities. **New 'thinking' status for Video Agents** We have introduced a new `thinking` state to the Video Agent response object to provide better visibility into agent processing workflows. * Updated `POST /v3/video-agents` * The `status` field in the response now includes the `thinking` enum value. * Integration note: Ensure your client-side parsers are prepared to handle this new status value in the response body. **Updated Video Agent session retrieval and new video listing** We have refactored how resource data is handled in Video Agent sessions to improve performance. Additionally, we have introduced a new endpoint to fetch videos associated with a session. * **Breaking Change:** The `resources` property has been removed from the response body of `GET /v3/video-agents/{session_id}`. * **Migration:** To access resource details previously found in the session object, please use the new `GET /v3/video-agents/{session_id}/resources/{resource_id}` endpoint. * **New Endpoint:** Added `GET /v3/video-agents/{session_id}/videos` to retrieve a list of videos generated within a specific agent session. **Breaking change: Restructured Video Agent session management** We have updated the Video Agent API to simplify session handling. Please note that the previous `/v3/video-agents/sessions` path structure is deprecated and removed. * **Removed endpoints:** `POST /v3/video-agents/sessions`, `GET /v3/video-agents/sessions/{session_id}`, `POST /v3/video-agents/sessions/{session_id}/messages`, `GET /v3/video-agents/sessions/{session_id}/resources`, and `POST /v3/video-agents/sessions/{session_id}/stop` have been removed. * **Migration:** Replace existing calls with the new flattened endpoints under `/v3/video-agents/{session_id}`. * **New endpoints added:** * `GET /v3/video-agents/{session_id}` * `POST /v3/video-agents/{session_id}` * `GET /v3/video-agents/{session_id}/resources/{resource_id}` * `POST /v3/video-agents/{session_id}/stop` **New configuration options for Video Agent sessions** The `POST /v3/video-agents` endpoint now supports advanced control over session flow. * Added `mode`: Supports `generate` (default, one-shot) and `chat` (multi-turn, allows revisions and follow-ups). * Added `auto_proceed`: Enables automated progression through storyboards. * Added `skip_agentic_stop`: Provides granular control over agent stopping behavior. **API Operation ID update** The operation ID for `GET /v3/users/me` has been updated from `getUserMeV3` to `getCurrentUserV3` to maintain consistency across our SDKs. **Added support for custom voice creation** We have introduced a new endpoint to allow developers to programmatically create and add new voices to their HeyGen account. * Added `POST /v3/voices` to the API. **Refactored POST /v3/videos request body** We have updated the `POST /v3/videos` endpoint to use a discriminated union for improved type safety and flexibility. This change replaces the legacy flat request structure with dedicated schemas for creating videos from avatars versus images. * **Breaking Change:** The request body structure has been completely overhauled. You must now specify a type discriminator: use `CreateVideoFromAvatar` for digital twins/avatars or `CreateVideoFromImage` for custom image animation. * **Migration:** All properties previously passed at the top level of the request (e.g., `avatar_id`, `image_url`, `voice_id`, `script`) must now be nested within the appropriate schema based on the video source. * The operation ID for this endpoint has been updated from `createAvatarVideoV3` to `createVideo`. **Enhanced error messaging across all endpoints** We have updated the error response schemas and examples across the entire API suite. Developers can now expect more consistent and detailed error responses for common issues, including: * Improved `400 Bad Request` messages with clearer parameter validation feedback. * Standardized `401 Unauthorized` responses when API keys are missing or expired. * Consistent `429 Rate Limited` responses that align with standard retry headers. * Better descriptive error messages for resource-specific failures (e.g., `404 Not Found` for specific IDs). These updates ensure that your integrations can better handle exceptions and debugging. **HeyGen for Developers — New v3 API Surface** We've launched a new set of v3 endpoints across the HeyGen API, bringing a consistent interface, cursor-based pagination, and a unified asset input model to all major resources. What's new: * All v3 endpoints share a standard error format, cursor-based pagination (`has_more` / `next_token`), and consistent authentication via `X-Api-Key` or OAuth bearer token. * Asset inputs now use a type-discriminated union — pass files as `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }`, or `{ "type": "base64", "media_type": "...", "data": "..." }` across all endpoints. * New and updated endpoints include: Video Agent (`POST /v3/video-agents`), Videos (`POST /v3/videos`), Voices (`GET /v3/voices`, `POST /v3/voices/speech`), Video Translations (`POST /v3/video-translations`), Overdub (`POST /v3/overdubs`), Avatars (`POST /v3/avatars`), Assets (`POST /v3/assets`), Webhooks (`/v3/webhooks/*`), and User (`GET /v3/users/me`). The v1/v2 endpoints continue to work, but we recommend migrating to v3 for all new integrations. # Overview Source: https://developers.heygen.com/cli Get from zero to a generated video in minutes — right from your terminal. The HeyGen CLI gives developers and AI agents command-line access to HeyGen's video platform. It wraps the v3 API, outputs structured JSON by default, and works out of the box in scripts, CI pipelines, and agent workflows. ## 1. Install the CLI ```bash theme={null} curl -fsSL https://static.heygen.ai/cli/install.sh | bash ``` This installs the latest stable release into `~/.local/bin`. Verify the installation: ```bash theme={null} heygen --version ``` The CLI ships as a single binary with no runtime prerequisites. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) are supported. Windows support is coming soon — WSL is recommended in the meantime. ## 2. Authenticate Log in with your API key from [API dashboard](https://app.heygen.com/settings/api?nav=API): ```bash theme={null} heygen auth login ``` Paste your API key when prompted. The key is stored locally at `~/.heygen/credentials`. For CI/Docker/agent environments, set the environment variable instead — it takes precedence over stored credentials: ```bash theme={null} export HEYGEN_API_KEY=your-api-key ``` Verify your credentials: ```bash theme={null} heygen auth status ``` ## 3. Create a Video Send a prompt to the Video Agent and let it handle avatar, voice, and layout: ```bash theme={null} heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds" ``` ```json Output theme={null} { "data": { "session_id": "sess_abc123", "status": "generating", "video_id": "vid_xyz789", "created_at": 1711288320 } } ``` The CLI returns immediately with structured JSON. Your video is generating in the background. For full control over every parameter, use `video create` with a JSON body: ```bash theme={null} heygen video create -d '{ "type": "avatar", "avatar_id": "avt_angela_01", "script": "Welcome to our Q4 earnings call.", "voice_id": "1bd001e7e50f421d891986aad5e3e5d2" }' ``` Use `--request-schema` on any command to discover the expected JSON fields — no auth required: ```bash theme={null} heygen video create --request-schema heygen video-agent create --request-schema ``` ## 4. Check Status Poll for the result using the `video_id` returned from step 3: ```bash theme={null} heygen video get vid_xyz789 ``` ```json Output theme={null} { "data": { "id": "vid_xyz789", "title": "Product launch explainer", "status": "completed", "video_url": "https://files.heygen.com/video/vid_xyz789.mp4", "thumbnail_url": "https://files.heygen.com/thumb/vid_xyz789.jpg", "duration": 32.5, "created_at": 1711288320, "completed_at": 1711288452 } } ``` Status moves through `pending` → `processing` → `completed` or `failed`. If the video fails, the response includes `failure_code` and `failure_message` fields. **Tip:** Add `--wait` to the create command to block until the video is ready instead of polling manually. The default timeout is 20 minutes — override with `--timeout 30m`. On timeout, the CLI exits with code `4` and prints the last known resource state along with a hint to resume polling manually. ## 5. Download the Video Once complete, download to a local file: ```bash theme={null} heygen video download vid_xyz789 --output-path ./launch-video.mp4 ``` ```json Output theme={null} { "asset": "video", "message": "Downloaded video to ./launch-video.mp4", "path": "./launch-video.mp4" } ``` If the video was created with captions enabled, you can download the captioned version: ```bash theme={null} heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4 ``` # Commands Source: https://developers.heygen.com/commands Complete command reference for the HeyGen CLI, organized by resource. All commands follow the pattern `heygen `. The command surface is auto-generated from HeyGen's OpenAPI specification — when new v3 endpoints ship, the CLI picks them up automatically. Run `heygen --help` for detailed usage and examples on any command. Use `--request-schema` or `--response-schema` on any command to see the full JSON schema for its request or response — no auth required. ## Video Agent Create videos from text prompts using AI. The agent picks avatar, voice, and layout automatically. | Command | API Endpoint | Description | | ------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------- | | `heygen video-agent create` | `POST /v3/video-agents` | Create a video from a prompt | | `heygen video-agent get ` | `GET /v3/video-agents/{session_id}` | Get session status and messages | | `heygen video-agent send ` | `POST /v3/video-agents/{session_id}` | Send a follow-up message or request revision | | `heygen video-agent stop ` | `POST /v3/video-agents/{session_id}/stop` | Stop an in-progress session | | `heygen video-agent resources get ` | `GET /v3/video-agents/{session_id}/resources/{resource_id}` | Get a session resource | | `heygen video-agent styles list` | `GET /v3/video-agents/styles` | List available video styles | | `heygen video-agent videos list ` | `GET /v3/video-agents/{session_id}/videos` | List videos produced by a session | ### Flags for `video-agent create` | Flag | Description | | ----------------------- | -------------------------------------------------------------------- | | `--prompt ` | The message/prompt for video generation (required) | | `--mode ` | `generate` (default, one-shot) or `chat` (multi-turn with revisions) | | `--avatar-id ` | Specific avatar ID to use | | `--voice-id ` | Specific voice ID to use for narration | | `--style-id ` | Style ID from `video-agent styles list` | | `--orientation ` | `landscape` or `portrait` (auto-detected if omitted) | | `--incognito-mode` | Disable memory injection and extraction for this session | | `--callback-url ` | Webhook URL for completion/failure notifications | | `--callback-id ` | ID echoed back in the webhook payload | ## Videos Create, list, retrieve, and delete avatar videos with full parameter control. | Command | API Endpoint | Description | | ---------------------------------- | ------------------------------ | --------------------------------------- | | `heygen video create` | `POST /v3/videos` | Create a video with explicit parameters | | `heygen video list` | `GET /v3/videos` | List your videos | | `heygen video get ` | `GET /v3/videos/{video_id}` | Get video details and status | | `heygen video delete ` | `DELETE /v3/videos/{video_id}` | Delete a video | | `heygen video download ` | Client-side | Download a video file to disk | ### Flags for `video create` `video create` uses a discriminated union request body — the `type` field determines which fields are valid. Pass the full body with `-d`: ```bash theme={null} # Avatar-based video heygen video create -d '{ "type": "avatar", "avatar_id": "avt_angela_01", "script": "Hello world", "voice_id": "1bd001e7e50f421d891986aad5e3e5d2" }' # Image-based video heygen video create -d '{ "type": "image", "image": {"type": "url", "url": "https://example.com/photo.jpg"}, "script": "Hello", "voice_id": "1bd001e7e50f421d891986aad5e3e5d2" }' ``` Run `heygen video create --request-schema` to see all available fields. ### Flags for `video list` | Flag | Description | | ------------------ | --------------------------------------------------------- | | `--limit ` | Maximum items per page (1–100, default 10) | | `--token ` | Pagination cursor from a previous response's `next_token` | | `--folder-id ` | Filter videos by folder ID | | `--title ` | Filter videos by title substring | ### Flags for `video download` | Flag | Description | | ---------------------- | -------------------------------------------- | | `--output-path ` | Output file path (default: `{video-id}.mp4`) | | `--asset ` | `video` (default) or `captioned` | ## Avatars Browse and manage avatars and their looks (outfits/styles). | Command | API Endpoint | Description | | ----------------------------------------- | ------------------------------------- | ------------------------ | | `heygen avatar create` | `POST /v3/avatars` | Create an avatar | | `heygen avatar list` | `GET /v3/avatars` | List avatar groups | | `heygen avatar get ` | `GET /v3/avatars/{group_id}` | Get avatar group details | | `heygen avatar looks list` | `GET /v3/avatars/looks` | List avatar looks | | `heygen avatar looks get ` | `GET /v3/avatars/looks/{look_id}` | Get avatar look details | | `heygen avatar looks update ` | `PATCH /v3/avatars/looks/{look_id}` | Rename an avatar look | | `heygen avatar consent create ` | `POST /v3/avatars/{group_id}/consent` | Initiate a consent flow | ### Filter flags for `avatar list` | Flag | Description | | --------------------- | ----------------------------------------- | | `--ownership ` | `public` or `private` | | `--limit ` | Maximum items per page (1–50, default 20) | | `--token ` | Pagination cursor | ### Filter flags for `avatar looks list` | Flag | Description | | ---------------------- | -------------------------------------------------- | | `--group-id ` | Filter by avatar group | | `--avatar-type ` | `studio_avatar`, `digital_twin`, or `photo_avatar` | | `--ownership ` | `public` or `private` | | `--limit ` | Maximum items per page (1–50, default 20) | | `--token ` | Pagination cursor | The `id` field on a look is what you pass as `avatar_id` to `video create`. The look's `avatar_type` field determines which engines and request parameters are compatible. ## Voices Browse voices and generate speech audio. | Command | API Endpoint | Description | | ---------------------------- | ------------------------ | -------------------------------------------------- | | `heygen voice list` | `GET /v3/voices` | List voices | | `heygen voice create` | `POST /v3/voices` | Design a voice from a natural language description | | `heygen voice speech create` | `POST /v3/voices/speech` | Generate speech audio from text | ### Filter flags for `voice list` | Flag | Description | | ------------------- | ---------------------------------------- | | `--type ` | `public` (default) or `private` | | `--engine ` | Filter by voice engine (e.g. `starfish`) | | `--language ` | Filter by language name (e.g. `English`) | | `--gender ` | `male` or `female` | | `--limit ` | Results per page (1–100, default 20) | | `--token ` | Pagination cursor | ### Flags for `voice create` | Flag | Description | | ------------------ | --------------------------------------------------------------- | | `--prompt ` | Natural language description of the desired voice (required) | | `--gender ` | `male` or `female` | | `--locale ` | BCP-47 locale tag (e.g. `en-US`) | | `--seed ` | Increment to get a different batch of voice results (default 0) | ### Flags for `voice speech create` | Flag | Description | | --------------------- | -------------------------------------------------- | | `--text ` | Text to synthesize (required) | | `--voice-id ` | Voice ID to use (required) | | `--speed ` | Playback speed multiplier, `0.5`–`2.0` (default 1) | | `--language ` | Base language code (auto-detected if omitted) | | `--locale ` | BCP-47 locale tag | | `--input-type ` | `text` (default) or `ssml` | ## Lipsync Dub or replace audio on existing videos. | Command | API Endpoint | Description | | ------------------------------------ | ---------------------------------- | ------------------------------ | | `heygen lipsync create` | `POST /v3/lipsyncs` | Create a lipsync job | | `heygen lipsync list` | `GET /v3/lipsyncs` | List lipsync jobs | | `heygen lipsync get ` | `GET /v3/lipsyncs/{lipsync_id}` | Get lipsync details and status | | `heygen lipsync update ` | `PATCH /v3/lipsyncs/{lipsync_id}` | Update a lipsync title | | `heygen lipsync delete ` | `DELETE /v3/lipsyncs/{lipsync_id}` | Delete a lipsync | `lipsync create` requires a complex request body (video and audio sources use discriminated unions). Use `-d`: ```bash theme={null} cat request.json | heygen lipsync create -d - ``` Run `heygen lipsync create --request-schema` to see all available fields. ## Video Translate Translate videos into other languages with lip-sync. | Command | API Endpoint | Description | | --------------------------------------------------- | ------------------------------------------------------ | ----------------------------- | | `heygen video-translate create` | `POST /v3/video-translations` | Create a video translation | | `heygen video-translate list` | `GET /v3/video-translations` | List translations | | `heygen video-translate get ` | `GET /v3/video-translations/{id}` | Get translation details | | `heygen video-translate update ` | `PATCH /v3/video-translations/{id}` | Update a translation title | | `heygen video-translate delete ` | `DELETE /v3/video-translations/{id}` | Delete a translation | | `heygen video-translate languages list` | `GET /v3/video-translations/languages` | List supported languages | | `heygen video-translate proofreads create` | `POST /v3/video-translations/proofreads` | Create a proofread session | | `heygen video-translate proofreads get ` | `GET /v3/video-translations/proofreads/{id}` | Get proofread status | | `heygen video-translate proofreads generate ` | `POST /v3/video-translations/proofreads/{id}/generate` | Generate video from proofread | | `heygen video-translate proofreads srt get ` | `GET /v3/video-translations/proofreads/{id}/srt` | Download proofread SRT | | `heygen video-translate proofreads srt update ` | `PUT /v3/video-translations/proofreads/{id}/srt` | Upload edited SRT | ### Flags for `video-translate create` | Flag | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | `--output-languages ` | Target language names, comma-separated (required). Use `video-translate languages list` for valid values | | `--mode ` | `speed` or `precision` | | `--speaker-num ` | Number of speakers in source (improves separation) | | `--translate-audio-only` | Translate audio without lip-sync | | `--enable-caption` | Add captions to translated video | | `--input-language ` | Source language code (auto-detected if omitted) | | `--callback-url ` | Webhook URL for completion notifications | | `--title ` | Title for the translation job | ## Webhooks Manage webhook endpoints for event notifications. | Command | API Endpoint | Description | | --------------------------------------------- | ------------------------------------------------ | -------------------------- | | `heygen webhook endpoints create` | `POST /v3/webhooks/endpoints` | Create a webhook endpoint | | `heygen webhook endpoints list` | `GET /v3/webhooks/endpoints` | List webhook endpoints | | `heygen webhook endpoints update ` | `PATCH /v3/webhooks/endpoints/{id}` | Update a webhook endpoint | | `heygen webhook endpoints delete ` | `DELETE /v3/webhooks/endpoints/{id}` | Delete a webhook endpoint | | `heygen webhook endpoints rotate-secret ` | `POST /v3/webhooks/endpoints/{id}/rotate-secret` | Rotate signing secret | | `heygen webhook event-types list` | `GET /v3/webhooks/event-types` | List available event types | | `heygen webhook events list` | `GET /v3/webhooks/events` | List delivered events | ### Flags for `webhook endpoints create` | Flag | Description | | ------------------ | ----------------------------------------------------------------- | | `--url ` | Publicly accessible HTTPS URL (required) | | `--events ` | Comma-separated event types to subscribe to (omit for all events) | | `--entity-id ` | Scope this endpoint to a specific resource | Store the `secret` returned by `endpoints create` and `endpoints rotate-secret` securely — it is used to verify webhook signatures and will not be shown again. ## Assets Upload files for use in video creation. | Command | API Endpoint | Description | | --------------------- | ----------------- | -------------------------------- | | `heygen asset create` | `POST /v3/assets` | Upload a file to get an asset ID | ### Flags for `asset create` | Flag | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--file ` | Local file to upload (required). Max 32 MB. Supported types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), pdf | ## User | Command | API Endpoint | Description | | -------------------- | ------------------ | ------------------------------------------- | | `heygen user me get` | `GET /v3/users/me` | Get current user info, credits, and billing | ## Authentication | Command | Description | | -------------------- | ------------------------------------------------ | | `heygen auth login` | Authenticate interactively (prompts for API key) | | `heygen auth status` | Verify stored credentials and show account info | For CI/Docker, use the `HEYGEN_API_KEY` environment variable instead. It takes precedence over stored credentials. ## Utility Commands | Command | Description | | --------------------------------- | -------------------------------------------- | | `heygen config set ` | Set a persistent config value | | `heygen config get ` | Read a config value | | `heygen config list` | Show all config values and their sources | | `heygen update` | Self-update to the latest version | | `heygen update --version ` | Update to a specific version (e.g. `v0.1.0`) | ### Config keys | Key | Values | Description | | ----------- | --------------- | ------------------------------------------- | | `output` | `json`, `human` | Default output format (default: `json`) | | `analytics` | `true`, `false` | Enable or disable anonymous usage analytics | # Content Repurposing Source: https://developers.heygen.com/content-repurposing Turn blog posts, articles, and newsletters into video — reach audiences that don't read. ## The Problem You invest hours writing a great blog post. It reaches your readers — but misses the much larger audience that consumes content through video. Manually converting articles to video takes almost as long as writing them. ## How It Works ``` Written content → LLM extracts key points → Video Agent renders → Distribute on video platforms ``` An LLM reads your content and writes a production-quality video prompt — extracting the most compelling points and restructuring them for video. The same article can become a 90-second YouTube explainer, a 30-second TikTok, and a 60-second LinkedIn post. ## Build It Pull the article from your CMS, a URL, or a local file. ```python theme={null} # From a file with open("article.md") as f: article = f.read() # Or from a URL (use a proper extraction library for production) import requests article = requests.get("https://yourblog.com/posts/your-article").text ``` The LLM acts as a producer — extracting the most engaging points and structuring them for video. ```python theme={null} import anthropic client = anthropic.Anthropic() message = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=1024, messages=[{ "role": "user", "content": f"""You are a video producer converting a written article into a HeyGen Video Agent prompt. Read this article and create a 60-second video prompt that: 1. Opens with the most compelling insight or stat (hook) 2. Covers the 3 most important points — not everything, the best bits 3. Uses specific visual descriptions — what the viewer sees on screen 4. Ends with a CTA to read the full article 5. Matches the tone of the original Article: {article} Output ONLY the Video Agent prompt.""" }], ) video_prompt = message.content[0].text ``` **Don't summarize — adapt.** The LLM shouldn't just compress the article. It should identify the most *visual* and *engaging* points and restructure them for video. A great blog point might be boring on video, and vice versa. Submit the prompt. Attach any images or charts from the article as file inputs. ```python theme={null} resp = requests.post( "https://api.heygen.com/v3/video-agents", headers={ "X-Api-Key": HEYGEN_API_KEY, "Content-Type": "application/json", }, json={ "prompt": video_prompt, "files": [ {"type": "url", "url": "https://yourblog.com/images/chart.png"}, ], }, ) video_id = resp.json()["data"]["video_id"] ``` Then poll for completion — see [Video Agent docs](/docs/video-agent). One article can become multiple videos for different platforms: ```python theme={null} formats = [ {"platform": "YouTube", "duration": "90s", "orientation": "landscape", "style": "in-depth"}, {"platform": "TikTok/Reels", "duration": "30s", "orientation": "portrait", "style": "hook-driven"}, {"platform": "LinkedIn", "duration": "60s", "orientation": "landscape", "style": "professional"}, ] for fmt in formats: # Regenerate the LLM prompt with platform-specific instructions platform_prompt = generate_prompt_for(article, fmt) # Submit to Video Agent with the right orientation submit_video(platform_prompt, orientation=fmt["orientation"]) ``` ## Content Types That Convert Well | Content type | Video style | Tips | | -------------------- | -------------------- | ------------------------------------------------- | | **How-to articles** | Tutorial walkthrough | Step-by-step with text overlays | | **Listicles** | Quick tips | One point every 5–7 seconds, great for short-form | | **Opinion/analysis** | Thought leadership | Presenter-driven, conversational | | **Case studies** | Story-driven | Before/after structure, stats as highlights | | **Newsletters** | Weekly digest | Cover 3–5 highlights, keep it breezy | ## Automating the Pipeline ``` Blog CMS webhook → "New post published" ↓ Fetch article content ↓ LLM generates video prompt ↓ Video Agent renders ↓ Upload to YouTube / post to social ↓ Add video embed to original article ``` Trigger from a CMS webhook, cron job, or CI/CD. See [Automated Broadcast](/cookbook/video-agent/automated-broadcast) for scheduling and distribution patterns. ## Variations * **Teaser + full:** 15-second teaser for social, 90-second deep dive for YouTube * **Multi-language:** Generate in English, then [translate](/cookbook/video-agent/multilingual-content) for global audiences * **Podcast-to-video:** Extract audio highlights → write visual prompt → avatar presents the key takeaways *** ## Next Steps Generate original social content, not just repurposed articles. Automate the entire content → video → distribute pipeline. # Data Visualization Videos Source: https://developers.heygen.com/data-to-video Turn datasets, metrics, and algorithms into animated videos — charts that move, dashboards that update, patterns that evolve. ## Examples