> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create HeyGen Video > Generate a HeyGen Video with model `heygen-video-1` from a text prompt, a first-frame image, or reference images, videos, and audio. Select `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Prompts accept at most 5,000 Unicode characters. Duration is 5–15 whole seconds; resolution is 480p or 768p. Image-to-video follows the image proportions and ignores aspect_ratio. Reference-to-video requires at least one image or video, with at most nine images, three videos, three audio recordings, and twelve references total. Reference videos must be within a 1:4–4:1 ratio. Assets accept HTTPS URLs, uploaded asset IDs, or inline base64. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id} for completion and the download URL. Pass an Idempotency-Key header to retry safely; without a key, each submission creates a new generation. ## OpenAPI ````yaml /openapi/external-api.json post /v3/models/videos openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: >- Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Models description: '' - name: Filler Word Removal description: '' paths: /v3/models/videos: post: tags: - Models summary: Create HeyGen Video description: >- Generate a HeyGen Video with model `heygen-video-1` from a text prompt, a first-frame image, or reference images, videos, and audio. Select `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Prompts accept at most 5,000 Unicode characters. Duration is 5–15 whole seconds; resolution is 480p or 768p. Image-to-video follows the image proportions and ignores aspect_ratio. Reference-to-video requires at least one image or video, with at most nine images, three videos, three audio recordings, and twelve references total. Reference videos must be within a 1:4–4:1 ratio. Assets accept HTTPS URLs, uploaded asset IDs, or inline base64. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id} for completion and the download URL. Pass an Idempotency-Key header to retry safely; without a key, each submission creates a new generation. operationId: createModelVideo parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateModelVideoRequest' responses: '202': description: Accepted — submission acknowledged; poll for completion. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateModelVideoResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: Provide at least one reference image or video. param: reference_images doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '402': description: Insufficient credit content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: insufficient_credit message: >- Insufficient credits for the video and its references. Add credits or use a shorter video or fewer references. param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: asset_not_found message: Asset not found. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer '503': description: >- Temporarily unavailable — the request did not complete and is safe to retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: resource_not_ready message: >- Asset ingestion is temporarily unavailable. Retry with the same Idempotency-Key. security: - ApiKeyAuth: [] - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateModelVideoRequest: description: >- Body of POST /v3/models/videos: one schema per generation mode, selected by the required mode field. discriminator: mapping: image_to_video: $ref: '#/components/schemas/ImageToVideoRequest' reference_to_video: $ref: '#/components/schemas/ReferenceToVideoRequest' text_to_video: $ref: '#/components/schemas/TextToVideoRequest' propertyName: mode oneOf: - $ref: '#/components/schemas/TextToVideoRequest' - $ref: '#/components/schemas/ImageToVideoRequest' - $ref: '#/components/schemas/ReferenceToVideoRequest' title: CreateModelVideoRequest CreateModelVideoResponse: properties: video_id: description: Video identifier to use when polling for the result. title: Video Id type: string status: const: pending default: pending description: The request has been accepted for processing. title: Status type: string required: - video_id title: CreateModelVideoResponse type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message ImageToVideoRequest: additionalProperties: false properties: model: const: heygen-video-1 description: Required video generation model. Only heygen-video-1 is supported. title: Model type: string prompt: description: >- Instructions for the video to generate. At most 5,000 Unicode characters. maxLength: 5000 minLength: 1 title: Prompt type: string prompt_enhancement: default: turbo description: >- Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo. enum: - turbo - quality - default - disabled title: Prompt Enhancement type: string duration: default: 5 description: >- Requested video duration in whole seconds, from 5 through 15 inclusive. maximum: 15 minimum: 5 title: Duration type: integer resolution: default: 768p description: 'Output resolution: 480p or 768p. Defaults to 768p.' enum: - 480p - 768p title: Resolution type: string aspect_ratio: anyOf: - enum: - '21:9' - '16:9' - '4:3' - '1:1' - '3:4' - '9:16' - adaptive type: string - type: 'null' default: null description: >- The output follows the image proportions, aligned to supported pixel dimensions. Any supplied aspect ratio is ignored. title: Aspect Ratio seed: anyOf: - maximum: 4294967295 minimum: 0 type: integer - type: 'null' default: null description: Generation seed. A random seed is chosen when omitted. title: Seed callback_url: anyOf: - type: string - type: 'null' default: null description: HTTPS webhook URL for the terminal generation event. title: Callback Url callback_id: anyOf: - maxLength: 256 type: string - type: 'null' default: null description: Client tracking ID echoed in the terminal webhook event. title: Callback Id mode: const: image_to_video description: Animate a first-frame image. title: Mode type: string image: description: First-frame image. discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Image required: - model - prompt - mode - image title: ImageToVideoRequest type: object ReferenceToVideoRequest: additionalProperties: false properties: model: const: heygen-video-1 description: Required video generation model. Only heygen-video-1 is supported. title: Model type: string prompt: description: >- Instructions for the video to generate. At most 5,000 Unicode characters. maxLength: 5000 minLength: 1 title: Prompt type: string prompt_enhancement: default: turbo description: >- Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo. enum: - turbo - quality - default - disabled title: Prompt Enhancement type: string duration: default: 5 description: >- Requested video duration in whole seconds, from 5 through 15 inclusive. maximum: 15 minimum: 5 title: Duration type: integer resolution: default: 768p description: 'Output resolution: 480p or 768p. Defaults to 768p.' enum: - 480p - 768p title: Resolution type: string aspect_ratio: default: adaptive description: >- Output aspect ratio. Adaptive uses the first reference image, or the first reference video when no images are supplied. Defaults to adaptive. enum: - '21:9' - '16:9' - '4:3' - '1:1' - '3:4' - '9:16' - adaptive title: Aspect Ratio type: string seed: anyOf: - maximum: 4294967295 minimum: 0 type: integer - type: 'null' default: null description: Generation seed. A random seed is chosen when omitted. title: Seed callback_url: anyOf: - type: string - type: 'null' default: null description: HTTPS webhook URL for the terminal generation event. title: Callback Url callback_id: anyOf: - maxLength: 256 type: string - type: 'null' default: null description: Client tracking ID echoed in the terminal webhook event. title: Callback Id mode: const: reference_to_video description: Generate guided by reference images, videos, and audio. title: Mode type: string reference_images: description: Reference images. At most nine. items: discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' maxItems: 9 title: Reference Images type: array reference_videos: description: Reference videos. At most three. items: discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' maxItems: 3 title: Reference Videos type: array reference_audio: description: Reference audio recordings. At most three. items: discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' maxItems: 3 title: Reference Audio type: array required: - model - prompt - mode title: ReferenceToVideoRequest type: object TextToVideoRequest: additionalProperties: false properties: model: const: heygen-video-1 description: Required video generation model. Only heygen-video-1 is supported. title: Model type: string prompt: description: >- Instructions for the video to generate. At most 5,000 Unicode characters. maxLength: 5000 minLength: 1 title: Prompt type: string prompt_enhancement: default: turbo description: >- Prompt enhancement mode: turbo, quality, or disabled. Defaults to turbo; default is an alias for turbo. enum: - turbo - quality - default - disabled title: Prompt Enhancement type: string duration: default: 5 description: >- Requested video duration in whole seconds, from 5 through 15 inclusive. maximum: 15 minimum: 5 title: Duration type: integer resolution: default: 768p description: 'Output resolution: 480p or 768p. Defaults to 768p.' enum: - 480p - 768p title: Resolution type: string aspect_ratio: default: '16:9' description: Output aspect ratio for text-to-video. Defaults to 16:9. enum: - '21:9' - '16:9' - '4:3' - '1:1' - '3:4' - '9:16' title: Aspect Ratio type: string seed: anyOf: - maximum: 4294967295 minimum: 0 type: integer - type: 'null' default: null description: Generation seed. A random seed is chosen when omitted. title: Seed callback_url: anyOf: - type: string - type: 'null' default: null description: HTTPS webhook URL for the terminal generation event. title: Callback Url callback_id: anyOf: - maxLength: 256 type: string - type: 'null' default: null description: Client tracking ID echoed in the terminal webhook event. title: Callback Id mode: const: text_to_video description: Generate from the prompt alone. title: Mode type: string required: - model - prompt - mode title: TextToVideoRequest type: object StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message AssetId: additionalProperties: false description: Asset input via HeyGen asset ID from the asset upload endpoint. properties: type: const: asset_id description: Input type discriminator title: Type type: string asset_id: description: HeyGen asset ID from the asset upload endpoint title: Asset Id type: string required: - type - asset_id title: AssetId type: object AssetBase64: additionalProperties: false description: Asset input via base64-encoded content. properties: type: const: base64 description: Input type discriminator title: Type type: string media_type: description: MIME type of the encoded content (e.g. "image/png") title: Media Type type: string data: description: Base64-encoded file content title: Data type: string required: - type - media_type - data title: AssetBase64 type: object x-mcp-visible: false AssetUrl: additionalProperties: false description: Asset input via publicly accessible HTTPS URL. properties: type: const: url description: Input type discriminator title: Type type: string url: description: Publicly accessible HTTPS URL for the asset title: Url type: string required: - type - url title: AssetUrl type: object responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````