---
title: "Create HeyGen Video"
method: POST
path: "/v3/models/videos"
tags: ["Models"]
---

# Create HeyGen Video

`POST /v3/models/videos`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/models/videos`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Generates a scene with its sound from a prompt using HeyGen Video (`heygen-video-1`). Set `mode` to `text_to_video`, `image_to_video` or `reference_to_video`; reference-to-video takes up to fifteen references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a `video_id`; poll GET /v3/models/videos/{video_id}. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use POST /v3/videos.

## Headers

- `Idempotency-Key` string

## Request body

- union: Body of POST /v3/models/videos: one schema per generation mode, selected by the required mode field.
  - TextToVideoRequest
    - `end_user_id` string, nullable: Stable, opaque end-user identifier in your application, scoped to the authenticated workspace. Use 1–128 non-whitespace characters without personal information. Used for usage attribution and abuse investigation; does not change billing, authorization, or rate limits.
    - `mode` 'text_to_video', required: Generate from the prompt alone.
    - `model` 'heygen-video-1', required: Required video generation model. Only heygen-video-1 is supported.
    - `prompt` string, required: Instructions for the video to generate. At most 16,000 Unicode characters.
    - `prompt_enhancement` 'turbo' | 'quality' | 'default' | 'disabled' | 'ultraquality': Prompt enhancement mode: turbo, quality, ultraquality, or disabled. Defaults to quality; default is an alias for turbo.
    - `resolution` '480p' | '768p' | '1080p' | '2k': Output resolution: 480p, 768p, 1080p, or 2k. Defaults to 768p. At 1080p and 2k, text-to-video and reference-to-video require aspect_ratio 16:9 or 9:16; image-to-video follows the image proportions.
    - `duration` union: Requested video duration: whole seconds from 5 through 30, or auto. Defaults to 5 when omitted. Above 15 requires text_to_video or image_to_video, 480p/768p/1080p/2k, and turbo/default/quality enhancement. Auto estimates quoted speech with an 8-second minimum and the maximum supported by these settings. Generation and billing use the resolved duration.
      - integer
      - 'auto'
    - `aspect_ratio` '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Output aspect ratio for text-to-video. Defaults to 16:9.
    - `seed` integer, nullable: Generation seed. A random seed is chosen when omitted.
    - `callback_url` string, nullable: HTTPS webhook URL for the terminal generation event.
    - `callback_id` string, nullable: Client tracking ID echoed in the terminal webhook event.
  - ImageToVideoRequest
    - `end_user_id` string, nullable: Stable, opaque end-user identifier in your application, scoped to the authenticated workspace. Use 1–128 non-whitespace characters without personal information. Used for usage attribution and abuse investigation; does not change billing, authorization, or rate limits.
    - `mode` 'image_to_video', required: Animate a first-frame image.
    - `model` 'heygen-video-1', required: Required video generation model. Only heygen-video-1 is supported.
    - `prompt` string, required: Instructions for the video to generate. At most 16,000 Unicode characters.
    - `prompt_enhancement` 'turbo' | 'quality' | 'default' | 'disabled' | 'ultraquality': Prompt enhancement mode: turbo, quality, ultraquality, or disabled. Defaults to quality; default is an alias for turbo.
    - `resolution` '480p' | '768p' | '1080p' | '2k': Output resolution: 480p, 768p, 1080p, or 2k. Defaults to 768p. At 1080p and 2k, text-to-video and reference-to-video require aspect_ratio 16:9 or 9:16; image-to-video follows the image proportions.
    - `duration` union: Requested video duration: whole seconds from 5 through 30, or auto. Defaults to 5 when omitted. Above 15 requires text_to_video or image_to_video, 480p/768p/1080p/2k, and turbo/default/quality enhancement. Auto estimates quoted speech with an 8-second minimum and the maximum supported by these settings. Generation and billing use the resolved duration.
      - integer
      - 'auto'
    - `aspect_ratio` '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | 'adaptive', nullable: The output follows the image proportions, aligned to supported pixel dimensions. Any supplied aspect ratio is ignored.
    - `seed` integer, nullable: Generation seed. A random seed is chosen when omitted.
    - `callback_url` string, nullable: HTTPS webhook URL for the terminal generation event.
    - `callback_id` string, nullable: Client tracking ID echoed in the terminal webhook event.
    - `image` union, required: First-frame image.
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content
  - ReferenceToVideoRequest
    - `end_user_id` string, nullable: Stable, opaque end-user identifier in your application, scoped to the authenticated workspace. Use 1–128 non-whitespace characters without personal information. Used for usage attribution and abuse investigation; does not change billing, authorization, or rate limits.
    - `mode` 'reference_to_video', required: Generate guided by reference images, videos, and audio.
    - `model` 'heygen-video-1', required: Required video generation model. Only heygen-video-1 is supported.
    - `prompt` string, required: Instructions for the video to generate. At most 16,000 Unicode characters.
    - `prompt_enhancement` 'turbo' | 'quality' | 'default' | 'disabled' | 'ultraquality': Prompt enhancement mode: turbo, quality, ultraquality, or disabled. Defaults to quality; default is an alias for turbo.
    - `resolution` '480p' | '768p' | '1080p' | '2k': Output resolution: 480p, 768p, 1080p, or 2k. Defaults to 768p. At 1080p and 2k, text-to-video and reference-to-video require aspect_ratio 16:9 or 9:16; image-to-video follows the image proportions.
    - `duration` union: Whole seconds from 5 through 15, or auto. Defaults to 5. Auto estimates quoted speech between 8 and 15 seconds.
      - integer
      - 'auto'
    - `aspect_ratio` '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | 'adaptive': Output aspect ratio. Adaptive uses the first reference image, or the first reference video when no images are supplied; audio-only references use 16:9. Defaults to adaptive.
    - `seed` integer, nullable: Generation seed. A random seed is chosen when omitted.
    - `callback_url` string, nullable: HTTPS webhook URL for the terminal generation event.
    - `callback_id` string, nullable: Client tracking ID echoed in the terminal webhook event.
    - `reference_images` union[]: Reference images. At most nine.
      - union
        - AssetUrl: Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required: Input type discriminator
          - `url` string, required: Publicly accessible HTTPS URL for the asset
        - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required: Input type discriminator
          - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
        - AssetBase64: Asset input via base64-encoded content.
          - `type` 'base64', required: Input type discriminator
          - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
          - `data` string, required: Base64-encoded file content
    - `reference_videos` union[]: Reference videos. At most three, sharing a 15-second budget. Use all footage when it fits; otherwise keep up to the first five seconds of each video and share the remaining budget equally among videos with footage remaining.
      - union
        - AssetUrl: Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required: Input type discriminator
          - `url` string, required: Publicly accessible HTTPS URL for the asset
        - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required: Input type discriminator
          - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
        - AssetBase64: Asset input via base64-encoded content.
          - `type` 'base64', required: Input type discriminator
          - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
          - `data` string, required: Base64-encoded file content
    - `reference_audio` union[]: Reference audio recordings. At most three.
      - union
        - AssetUrl: Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required: Input type discriminator
          - `url` string, required: Publicly accessible HTTPS URL for the asset
        - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required: Input type discriminator
          - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
        - AssetBase64: Asset input via base64-encoded content.
          - `type` 'base64', required: Input type discriminator
          - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
          - `data` string, required: Base64-encoded file content

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateModelVideoResponse
    - `video_id` string, required: Video identifier to use when polling for the result.
    - `status` 'pending': The request has been accepted for processing.
    - `input_video_duration` number, nullable: Total reference-video duration allocated for billing, in seconds, with a shared 15-second budget.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `402`: Insufficient credit
- `404`: Resource not found
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded
- `503`: Temporarily unavailable — the request did not complete and is safe to retry.

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/models/videos/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)