---
title: HeyGen Video 1.0 | Runware Docs
url: https://runware.ai/docs/models/heygen-video-1-0
description: Prompt-driven video generation with native dialogue, ambience, and sound effects
---
# HeyGen Video 1.0

![HeyGen Video 1.0](https://assets.runware.ai/covers/heygen-video-1-0.jpg)

HeyGen Video 1.0 is HeyGen's video generation model for short clips with synchronized audio. It generates the full frame from a text prompt, a first-frame image, or up to 12 image, video, and audio references, and produces dialogue, ambience, and sound effects in the same pass, with no separate lip-sync step. It outputs 5 to 15 second clips at 480p or 768p, suited to presenter shots, product and training content, and social video.

- **Status**: live
- **ID**: `heygen:video@1.0`
- Try in Playground
- **Creator**: HeyGen
- **Release Date**: September 30, 2026
- **Capabilities**: Text to Video, Image to Video, Video to Video, Audio to Video, Checkpoint, Audio

## Pricing

$0.0107 $0.0214 from, per second

**Rates** (per second)

- 480p, from text or an image: `$0.0107 $0.0214`
- 768p, from text or an image: `$0.016 $0.0321`
- 480p, from references: `$0.0214 $0.0428`
- 768p, from references: `$0.0321 $0.0642`
- 480p, per second of reference video, added to the output: `$0.0214 $0.0428`
- 768p, per second of reference video, added to the output: `$0.0321 $0.0642`

[How pricing works](https://runware.ai/docs/models-api/pricing)

## Compatibility & Validation

Inside `inputs`, `frameImages` cannot be used with `referenceImages`, `referenceVideos`, or `referenceAudios`.

---

`inputs.frameImages` cannot be used with `width/height`.

---

When `inputs.referenceAudios` is provided, `inputs.referenceImages` or `inputs.referenceVideos` is required.

---

`resolution` cannot be used with `width/height`.

---

When `resolution` is provided, `inputs.frameImages`, `inputs.referenceImages`, or `inputs.referenceVideos` is required.

---

`width` and `height` must be used together.

---

The following dimension combinations are supported:

| Configuration | Dimensions |
| --- | --- |
| `480p (~21:9)` | `960x416` |
| `480p (~16:9)` | `832x480` |
| `480p (4:3)` | `640x480` |
| `480p (1:1)` | `480x480` |
| `480p (3:4)` | `480x640` |
| `480p (~9:16)` | `480x832` |
| `768p (~21:9)` | `1536x672` |
| `768p (~16:9)` | `1344x768` |
| `768p (4:3)` | `1024x768` |
| `768p (1:1)` | `768x768` |
| `768p (3:4)` | `768x1024` |
| `768p (~9:16)` | `768x1344` |

## Request Parameters

**API Options**

Platform-level options for task execution and delivery.

### [taskType](https://runware.ai/docs/models/heygen-video-1-0#request-tasktype)

- **Type**: `string`
- **Required**: true
- **Value**: `videoInference`

Identifier for the type of task being performed.

### [taskUUID](https://runware.ai/docs/models/heygen-video-1-0#request-taskuuid)

- **Type**: `string`
- **Required**: true
- **Format**: `UUID v4`

UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.

### [outputType](https://runware.ai/docs/models/heygen-video-1-0#request-outputtype)

- **Type**: `string`
- **Default**: `URL`

Video output type.

**Allowed values**: `URL`

### [outputFormat](https://runware.ai/docs/models/heygen-video-1-0#request-outputformat)

- **Type**: `string`
- **Default**: `MP4`

Specifies the file format of the generated output. The available values depend on the task type and the specific model's capabilities.

- \`MP4\`: Widely supported video container (H.264), recommended for general use.
- \`WEBM\`: Optimized for web delivery.
- \`MOV\`: QuickTime format, common in professional workflows (Apple ecosystem).

**Allowed values**: `MP4` `WEBM` `MOV`

### [outputQuality](https://runware.ai/docs/models/heygen-video-1-0#request-outputquality)

- **Type**: `integer`
- **Min**: `20`
- **Max**: `99`
- **Default**: `95`

Compression quality of the output. Higher values preserve quality but increase file size.

### [webhookURL](https://runware.ai/docs/models/heygen-video-1-0#request-webhookurl)

- **Type**: `string`
- **Format**: `uri`

Webhook URL that receives JSON responses via HTTP POST when generation tasks complete. For batch requests with multiple results, each completed item triggers a separate webhook call as it becomes available.

**Learn more** (1 resource):

- [Webhooks](https://runware.ai/docs/models-api/webhooks) (platform)

### [deliveryMethod](https://runware.ai/docs/models/heygen-video-1-0#request-deliverymethod)

- **Type**: `string`
- **Default**: `async`

Determines how the API delivers task results.

**Allowed values**:

- `async` Returns an immediate acknowledgment with the task UUID. Poll for results using getResponse. Required for long-running tasks like video generation.

**Learn more** (1 resource):

- [Task Polling](https://runware.ai/docs/models-api/task-polling) (platform)

### [uploadEndpoint](https://runware.ai/docs/models/heygen-video-1-0#request-uploadendpoint)

- **Type**: `string`
- **Format**: `uri`

Specifies a URL where the generated content will be automatically uploaded using the HTTP PUT method. The raw binary data of the media file is sent directly as the request body. For secure uploads to cloud storage, use presigned URLs that include temporary authentication credentials.

**Common use cases:**

- **Cloud storage**: Upload directly to S3 buckets, Google Cloud Storage, or Azure Blob Storage using presigned URLs.
- **CDN integration**: Upload to content delivery networks for immediate distribution.

```text
// S3 presigned URL for secure upload
https://your-bucket.s3.amazonaws.com/generated/content.mp4?X-Amz-Signature=abc123&X-Amz-Expires=3600

// Google Cloud Storage presigned URL
https://storage.googleapis.com/your-bucket/content.jpg?X-Goog-Signature=xyz789

// Custom storage endpoint
https://storage.example.com/uploads/generated-image.jpg
```

The content data will be sent as the request body to the specified URL when generation is complete.

### [safety](https://runware.ai/docs/models/heygen-video-1-0#request-safety)

- **Path**: `safety.checkContent`
- **Type**: `object (2 properties)`

Content safety checking configuration for video generation.

#### [checkContent](https://runware.ai/docs/models/heygen-video-1-0#request-safety-checkcontent)

- **Path**: `safety.checkContent`
- **Type**: `boolean`

Enable or disable content safety checking. Increases total generation time.

#### [mode](https://runware.ai/docs/models/heygen-video-1-0#request-safety-mode)

- **Path**: `safety.mode`
- **Type**: `string`
- **Default**: `fast`

Safety checking mode for video generation.

**Allowed values**:

- `fast` Checks key frames.
- `full` Checks all frames.

### [ttl](https://runware.ai/docs/models/heygen-video-1-0#request-ttl)

- **Type**: `integer`
- **Min**: `60`

Time-to-live (TTL) in seconds for generated content. Only applies when `outputType` is `URL`.

### [includeCost](https://runware.ai/docs/models/heygen-video-1-0#request-includecost)

- **Type**: `boolean`

Include task cost in the response.

### [numberResults](https://runware.ai/docs/models/heygen-video-1-0#request-numberresults)

- **Type**: `integer`
- **Min**: `1`
- **Max**: `4`
- **Default**: `1`

Number of results to generate. Each result uses a different seed, producing variations of the same parameters.

**Inputs**

Input resources for the task (images, audio, etc). These must be nested inside the \`inputs\` object.

### [referenceImages](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-referenceimages)

- **Path**: `inputs.referenceImages`
- **Type**: `array of strings`
- **Min items**: `1`
- **Max items**: `9`
- **File size (each)**: `up to 16 MB`

List of reference images (UUID, URL, Data URI, or Base64).

### [frameImages](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-frameimages)

- **Path**: `inputs.frameImages`
- **Type**: `array of strings or objects`
- **Min items**: `items: 1`
- **File size (each)**: `up to 16 MB`

An array of frame-specific image inputs to guide video generation. Each item can be either a plain image input (UUID, URL, Data URI, or Base64) or an object that pairs an image with a target position in the video.

The `frameImages` parameter allows you to constrain specific frames within the video sequence, ensuring that particular visual content appears at designated points. Position can be specified using `frame` (named positions or frame indices) or `timestamp` (seconds), depending on model support. This is different from `referenceImages`, which provide overall visual guidance without constraining specific timeline positions.

When the `frame` parameter is omitted, automatic distribution rules apply:

- **1 image**: Used as the first frame.

**Examples**:

**Shorthand format:** When you don't need to specify a frame position, you can pass a plain image input directly.

```json
"frameImages": [
  "aac49721-1964-481a-ae78-8a4e29b91402"
]
```

**Object format:** When you need to specify a position, use an object with `image` and either `frame` or `timestamp` (model-dependent).

```json
"frameImages": [
  {
    "image": "aac49721-1964-481a-ae78-8a4e29b91402",
    "frame": "first"
  }
]
```

**Format 1: string[]**:

- **Type**: `string`

Image input (UUID, URL, Data URI, or Base64).

**Format 2: object[]**:

#### [image](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-frameimages-format-2-image)

- **Path**: `inputs.frameImages.image`
- **Type**: `string`
- **Required**: true

Image input (UUID, URL, Data URI, or Base64).

#### [frame](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-frameimages-format-2-frame)

- **Path**: `inputs.frameImages.frame`
- **Type**: `object`

Target frame position for the image. This model only supports the first frame.

**Allowed values**:

- `first` First frame of the video.
- `0` Frame index 0 (first frame).

### [referenceVideos](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-referencevideos)

- **Path**: `inputs.referenceVideos`
- **Type**: `array of strings`
- **Min items**: `1`
- **Max items**: `3`
- **File size (each)**: `up to 32 MB`

List of reference videos (UUID or URL).

### [referenceAudios](https://runware.ai/docs/models/heygen-video-1-0#request-inputs-referenceaudios)

- **Path**: `inputs.referenceAudios`
- **Type**: `array of strings`
- **Min items**: `1`
- **Max items**: `3`
- **File size (each)**: `up to 32 MB`

List of reference audios (UUID or URL).

**Core Parameters**

Primary parameters that define the task output.

### [model](https://runware.ai/docs/models/heygen-video-1-0#request-model)

- **Type**: `string`
- **Required**: true
- **Value**: `heygen:video@1.0`

Identifier of the model to use for generation.

**Learn more** (3 resources):

- [Text To Image: Model Selection](https://runware.ai/docs/learn/text-to-image#model-selection) (learn)
- [Image Inpainting: Model Specialized Inpainting Models](https://runware.ai/docs/learn/image-inpainting#model-specialized-inpainting-models) (learn)
- [Image Outpainting: Other Critical Parameters](https://runware.ai/docs/learn/image-outpainting#other-critical-parameters) (learn)

### [positivePrompt](https://runware.ai/docs/models/heygen-video-1-0#request-positiveprompt)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `32000`

Text prompt describing elements to include in the generated output.

**Learn more** (1 resource):

- [Prompts](https://runware.ai/docs/learn/prompts) (learn)

### [width](https://runware.ai/docs/models/heygen-video-1-0#request-width)

- **Type**: `integer`
- **Paired with**: height

Width of the generated media in pixels.

**Learn more** (2 resources):

- [Dimensions](https://runware.ai/docs/learn/dimensions) (learn)
- [Image Outpainting: Dimensions Critical For Outpainting](https://runware.ai/docs/learn/image-outpainting#dimensions-critical-for-outpainting) (learn)

### [height](https://runware.ai/docs/models/heygen-video-1-0#request-height)

- **Type**: `integer`
- **Paired with**: width

Height of the generated media in pixels.

**Learn more** (2 resources):

- [Dimensions](https://runware.ai/docs/learn/dimensions) (learn)
- [Image Outpainting: Dimensions Critical For Outpainting](https://runware.ai/docs/learn/image-outpainting#dimensions-critical-for-outpainting) (learn)

### [resolution](https://runware.ai/docs/models/heygen-video-1-0#request-resolution)

- **Type**: `string`
- **Default**: `768p`

Resolution preset for the output. When used with input media, automatically matches the aspect ratio from the input.

**Allowed values**: `480p` `768p`

### [duration](https://runware.ai/docs/models/heygen-video-1-0#request-duration)

- **Type**: `integer`
- **Min**: `5`
- **Max**: `15`
- **Default**: `5`

Length of the generated video in seconds. The total number of frames produced is determined by duration multiplied by the model's frame rate (fps).

### [seed](https://runware.ai/docs/models/heygen-video-1-0#request-seed)

- **Type**: `integer`
- **Min**: `0`
- **Max**: `4294967295`

Random seed for reproducible generation. When not provided, a random seed is generated in the unsigned 32-bit range.

**Settings**

Technical parameters to fine-tune the inference process. These must be nested inside the \`settings\` object.

### [promptEnhancement](https://runware.ai/docs/models/heygen-video-1-0#request-settings-promptenhancement)

- **Path**: `settings.promptEnhancement`
- **Type**: `string`
- **Default**: `turbo`

Level of automatic prompt rewriting applied before generation.

**Allowed values**:

- `disabled` No prompt rewriting. The prompt reaches the model exactly as written.
- `turbo` Fast rewriting.
- `quality` More thorough rewriting.

## Response Parameters

### [taskType](https://runware.ai/docs/models/heygen-video-1-0#response-tasktype)

- **Type**: `string`
- **Required**: true
- **Value**: `videoInference`

Identifier for the type of task this response belongs to.

### [taskUUID](https://runware.ai/docs/models/heygen-video-1-0#response-taskuuid)

- **Type**: `string`
- **Required**: true
- **Format**: `UUID v4`

UUID v4 identifier echoed from the original request, used to match async responses to their tasks.

### [videoUUID](https://runware.ai/docs/models/heygen-video-1-0#response-videouuid)

- **Type**: `string`
- **Required**: true
- **Format**: `UUID v4`

UUID of the output video.

### [videoURL](https://runware.ai/docs/models/heygen-video-1-0#response-videourl)

- **Type**: `string`
- **Format**: `uri`

URL of the output video.

### [videoBase64Data](https://runware.ai/docs/models/heygen-video-1-0#response-videobase64data)

- **Type**: `string`

Base64-encoded video data.

### [videoDataURI](https://runware.ai/docs/models/heygen-video-1-0#response-videodatauri)

- **Type**: `string`
- **Format**: `uri`

Data URI of the output video.

### [seed](https://runware.ai/docs/models/heygen-video-1-0#response-seed)

- **Type**: `integer`

The seed used for generation. If none was provided, shows the randomly generated seed.

### [NSFWContent](https://runware.ai/docs/models/heygen-video-1-0#response-nsfwcontent)

- **Type**: `boolean`

Flag indicating if NSFW content was detected.

### [cost](https://runware.ai/docs/models/heygen-video-1-0#response-cost)

- **Type**: `float`

Task cost in USD. Present when `includeCost` is set to `true` in the request.

## Examples

### text-to-video (text-to-video)

[Watch video](https://assets.runware.ai/examples/heygen-video-1-0/806d7203-48e8-4c66-be06-8b2581cd835f.mp4)

```json
{
  "taskType": "videoInference",
  "taskUUID": "61284338-3304-43e4-abb3-f49a7db02ca5",
  "model": "heygen:video@1.0",
  "positivePrompt": "Create a self-contained cinematic documentary title sequence in one continuous shot, composed for a 1344x768 landscape frame. Begin in an extreme macro view of a steel seismograph stylus scratching a thin black waveform onto slowly advancing cream paper. Fibers, ink bleed, screws, and vibration are sharply tactile. The camera glides backward just above the paper, following the newly drawn line as faint tremors make it quiver. Gradually reveal an empty, timeworn volcanic monitoring station: muted sage-green walls, analog gauges, paper charts, metal desks, coiled radio cables, amber task lamps, and moisture on a broad observation window. It is predawn, with cold cyan light outside and warm tungsten pools inside. Beyond the glass, a snow-streaked stratovolcano dominates the horizon beneath heavy charcoal clouds.\n\nAs the camera continues its slow, precise dolly backward, the tremor strengthens. Gauge needles twitch, a hanging metal lamp sways slightly, a ceramic mug ripples, and fine ceiling dust falls through the amber light. A narrow orange fissure opens near the volcano's summit, illuminating the underside of the clouds without becoming a huge explosive spectacle. The seismograph line in the foreground spikes violently. Settle into a centered, symmetrical wide composition with the moving seismograph paper low in the foreground and the volcano framed through the window. The room remains unoccupied, observational, credible, and grounded in real scientific detail.\n\nOver the darkened final composition, reveal the exact title “THE MOUNTAIN IS SPEAKING” in large, clean, condensed uppercase ivory lettering, centered and fully legible. Beneath it, add only the smaller line “A DOCUMENTARY SERIES”. Hold the final title steady for the closing beat with no other text, logos, captions, borders, or watermarks.\n\nArt direction: austere 1980s scientific realism, prestige natural-history documentary, restrained analogue texture, subtle 35mm film grain, gentle halation around practical lamps, deep blacks, sulfur-orange accents, cold blue dawn, controlled contrast, realistic scale and physics. Camera movement must remain smooth and deliberate with natural depth of field and no cuts, whip pans, or handheld shake.\n\nGenerate synchronized cinematic audio: close paper-feed mechanism, crisp stylus scratching, low electrical room hum, intermittent radio static, faint mountain wind against the window, gradually deepening subterranean rumble, soft glass and instrument-panel rattles, one restrained bowed-metal musical tone, then a sudden near-silence as the title settles. No speech, narration, crowd sounds, or dramatic trailer percussion.",
  "width": 1344,
  "height": 768
}
```

---

### text-to-video (text-to-video)

[Watch video](https://assets.runware.ai/examples/heygen-video-1-0/9ebc4e91-38f9-4b23-82fd-1f4504191a15.mp4)

```json
{
  "taskType": "videoInference",
  "taskUUID": "e7feb071-4dd3-4502-ab33-c010fc7c552d",
  "model": "heygen:video@1.0",
  "positivePrompt": "Create a premium landscape social media video ad for an independent mobile farrier service, grounded in authentic equestrian practice. Open on an extreme close-up of a skilled female farrier in a charcoal canvas apron drawing a rasp smoothly across the edge of a clean horse hoof; fine hoof shavings fall in crisp slow motion, with every stroke precisely synchronized to the gritty rasping sound. Hard cut to a medium eye-level shot inside an airy timber stable at cool early morning: the calm chestnut horse stands safely on three legs while the farrier lowers the freshly balanced hoof, runs a reassuring hand down the horse’s leg, then looks directly into camera. She says naturally with accurate lip synchronization: “Balanced feet make every stride feel better. Book your horse’s next trim today.” Cut on her final word to a low lateral tracking shot of the same horse walking comfortably beside its owner through the stable aisle, showing an even, relaxed stride. End on the horse’s confident hoof fall and a gentle tail swish. Refined documentary realism, tactile craftsmanship, slate blue shadows, warm chestnut and weathered oak, soft shafts of morning light, shallow depth of field, restrained handheld movement, clean editorial cuts. Authentic stable ambience throughout: quiet breathing, leather tack creaks, distant birds, soft hoofbeats, and subtle understated acoustic guitar beneath the dialogue. No captions, logos, watermarks, interface elements, exaggerated expressions, unsafe handling, or visible injuries.",
  "width": 1344,
  "height": 768
}
```

---

### first-frame (first-frame)

[Watch video](https://assets.runware.ai/examples/heygen-video-1-0/ec52615b-8586-40cc-b53e-3b9a49245528.mp4)

```json
{
  "taskType": "videoInference",
  "taskUUID": "24b7beaf-7268-4c63-8878-a9a0a1c387d0",
  "model": "heygen:video@1.0",
  "positivePrompt": "Continue directly and seamlessly from the supplied first frame as a premium vertical product showcase in one continuous shot. The metalworker maintains a poised editorial presence, slowly lowers the translucent amber visor with one gloved hand, then turns slightly toward the fabrication bench while keeping the sculptural helmet clearly visible. The camera makes a smooth, restrained push-in with a shallow 30-degree orbit around her upper body, revealing the hammered matte-black shell, curved side profile and amber visor from changing angles without altering the product design. She briefly activates the welding torch against a small steel plate already on the bench; a controlled blue-white arc creates elegant moving reflections across the visor and helmet contours, with a few realistic orange sparks falling safely downward. End on a confident three-quarter profile with the helmet dominating the frame. Preserve the same model, clothing, workshop, lighting direction and exact helmet construction throughout. Sophisticated industrial-fashion art direction, steel blue, charcoal and sodium orange palette, crisp premium detail, subtle atmospheric haze, realistic physical motion, no cuts, no scene change, no text, no logos, no additional people. Synchronized audio: a minimal percussive industrial-electronic pulse, quiet workshop room tone, the tactile click of the visor lowering and a brief authentic welding crackle; no speech.",
  "resolution": "768p",
  "inputs": {
    "frameImages": [
      "https://assets.runware.ai/assets/inputs/cfb9a552-4dc1-45ca-8396-3441b6d538c8.jpg"
    ]
  }
}
```

---

### reference-to-video (reference-to-video)

[Watch video](https://assets.runware.ai/examples/heygen-video-1-0/81bf996b-d394-47ea-be31-eafb518366d5.mp4)

```json
{
  "taskType": "videoInference",
  "taskUUID": "99ff99e3-19c4-4130-af1a-ceb48ae3a123",
  "model": "heygen:video@1.0",
  "positivePrompt": "Create a polished cinematic teaser and compact title sequence for a prestige conspiracy limited series called “THE QUIET LEDGER,” set inside a city’s flooded underground property archive. Compose in widescreen 16:9 for 768p. Use the reference image as the exact visual art-direction anchor: realistic water-damaged ledger paper, forensic ultraviolet glow, faded red municipal seals, oxidized teal shadows, restrained amber practical lights, steel shelving, damp institutional textures and elegant shallow-focus cinematography. Do not reproduce it as a static shot; build a coherent new sequence from its materials and atmosphere.\n\nUse the reference video as motion and camera-language guidance: the same patient forward dolly, subtle parallax through shelving, precise macro inserts, nearly imperceptible evidence-tag movement and controlled procedural suspense. Begin in near darkness as a filing drawer slides open by itself. Cut to extreme macro details: water crawling through paper fibers, parcel boundaries bleeding into one another, a steel date stamp descending, and a conservator’s black-gloved fingertip revealing erased handwriting beneath ultraviolet light. Transition through a match cut from a circular embossed seal to an overhead view of concentric water stains spreading across a city map. Finish on the open ledger at the end of the archive aisle as the camera slowly pushes closer and one previously blank line darkens as though hidden iron-gall ink is surfacing.\n\nSynchronize edits and physical actions to the supplied reference audio: paper taps motivate macro cuts, filing-drawer clicks motivate hard transitions, date-stamp impacts land on visual punctuation, and the low cello drone supports the continuous push into the archive. On the final deep impact, resolve to a stark, centered series title, “THE QUIET LEDGER,” in refined narrow ivory capitals subtly debossed into wet black paper; hold it cleanly while the room tone decays. No dialogue, no voice-over, no subtitles, no extra copy, no logos, no interface elements. Mood: intelligent institutional dread rather than horror, tactile and plausible, premium streaming-drama finish, restrained camera movement, natural material physics, coherent geography, crisp focal transitions and subtle 35mm grain.",
  "resolution": "768p",
  "inputs": {
    "referenceImages": [
      "https://assets.runware.ai/assets/inputs/86a3f29a-924c-44a4-8b16-f0a3a3e83de1.jpg"
    ],
    "referenceVideos": [
      "https://assets.runware.ai/assets/inputs/9495f060-3472-4c7a-b73a-024f70101d6c.mp4"
    ],
    "referenceAudios": [
      "https://assets.runware.ai/assets/inputs/838cf2c9-b907-4da8-bf35-2366289a5a3e.mp3"
    ]
  }
}
```