---
title: Keeping products, people and places with reference images — HeyGen Video 1.0 | Runware Docs
url: https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video
description: How to carry a product, a person or a location into a HeyGen Video 1.0 shot with inputs.referenceImages, address each one by label, and control the output shape.
---
### [Introduction](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#introduction)

Reference images let HeyGen Video 1.0 **build a new scene around things you supply**: a product, a person, a place. Pass photographs in `inputs.referenceImages`, name each one in the prompt by its label, and the color and markings of what you supplied **carry into the shot**.

This is the mode for **placing a real product in a new scene**, or for putting **the same person in front of the camera across a series**. The model composes the shot from the prompt and draws each subject from its reference, so the opening frame is the model's to choose.

[Watch video](https://runware.ai/docs/assets/output-hero.g7nCFK1Y.mp4)

*Three references, one shot: the runner, the bottle and the viewpoint. Play it with audio on.*

> **Prompt**: Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue.

**Picture 1: runner**:

![A studio portrait of a freckled trail runner with a short dark bob in a rust-orange running top against a gray backdrop](https://runware.ai/docs/assets/reference-runner.TAkCaTnt_Z1021vA.jpg)

> **Prompt**: A photoreal studio portrait of a trail runner in her early thirties with a short dark bob and light freckles across her nose, in a fitted rust-orange running top, waist up, facing the camera with a relaxed expression. Plain neutral gray backdrop, soft even studio light, real skin texture. No logos, brand names or printed words anywhere in frame.

**Picture 2: bottle**:

![A matte forest-green insulated water bottle with a cream bamboo lid and a small embossed mountain emblem on a white background](https://runware.ai/docs/assets/reference-bottle.CQbqVU5m_Zo7mqc.jpg)

> **Prompt**: A photoreal e-commerce packshot of an insulated stainless steel water bottle in matte forest green with a cream bamboo screw lid and a small embossed mountain emblem near the base, standing upright on a plain white background, front view, soft even studio light. No text anywhere on the bottle or in frame.

**Picture 3: viewpoint**:

![A clifftop viewpoint with a weathered wooden bench and dry-stone wall, a red-and-white striped lighthouse on the headland beyond](https://runware.ai/docs/assets/reference-viewpoint.D-4acCzC_ZqpcIv.jpg)

> **Prompt**: A photoreal landscape photograph of a coastal clifftop trail viewpoint on a clear morning: a weathered wooden bench and a low dry-stone wall in the foreground, and a red-and-white striped lighthouse standing on the headland beyond, with the sea far below. Soft morning light. No people, no logos, no printed words anywhere in frame.

This guide covers the request and its labels, placing a product, keeping a person, using several views of one product, and how the references decide the shape of the output.

### [The request](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#the-request)

References go in `inputs.referenceImages`, and the prompt refers to each one **by its position in that list**.

**TypeScript**:

```typescript
import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const [result] = await client.run({
  model: 'heygen:video@1.0',
  positivePrompt: 'Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle\'s forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue.',
  inputs: {
    referenceImages: [
      'https://example.com/refs/runner.jpg',
      'https://example.com/refs/bottle.jpg',
      'https://example.com/refs/viewpoint.jpg'
    ]
  },
  width: 1344,
  height: 768,
  duration: 8
})
```

**Python**:

```python
import asyncio
import os

from runware import Runware

async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        results = await client.run({
            "model": "heygen:video@1.0",
            "positivePrompt": "Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue.",
            "inputs": {
                "referenceImages": [
                    "https://example.com/refs/runner.jpg",
                    "https://example.com/refs/bottle.jpg",
                    "https://example.com/refs/viewpoint.jpg"
                ]
            },
            "width": 1344,
            "height": 768,
            "duration": 8
        })

asyncio.run(main())
```

**cURL**:

```bash
curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "videoInference",
      "taskUUID": "7a3d9e51-4c28-4f06-b1a9-e2c5f8073d16",
      "model": "heygen:video@1.0",
      "positivePrompt": "Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue.",
      "inputs": {
        "referenceImages": [
          "https://example.com/refs/runner.jpg",
          "https://example.com/refs/bottle.jpg",
          "https://example.com/refs/viewpoint.jpg"
        ]
      },
      "width": 1344,
      "height": 768,
      "duration": 8
    }
  ]'
```

**CLI**:

```bash
runware run heygen:video@1.0 \
  positivePrompt="Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue." \
  inputs.referenceImages.0=https://example.com/refs/runner.jpg \
  inputs.referenceImages.1=https://example.com/refs/bottle.jpg \
  inputs.referenceImages.2=https://example.com/refs/viewpoint.jpg \
  width=1344 \
  height=768 \
  duration=8
```

**JSON**:

```json
{
  "taskType": "videoInference",
  "taskUUID": "7a3d9e51-4c28-4f06-b1a9-e2c5f8073d16",
  "model": "heygen:video@1.0",
  "positivePrompt": "Shot on a large-format cinema camera with a 50mm lens at T2.8, locked off on a tripod at chest height. The trail runner from <Picture 1> stands at the clifftop viewpoint from <Picture 3>, beside the wooden bench, catching her breath after a run. She holds the water bottle from <Picture 2> loosely in her right hand at her side, its embossed mountain emblem facing the camera. She looks out to sea, then turns back toward the camera and smiles. Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>. Clear morning light, muted natural color. No other logos, brand names or printed words anywhere in frame. Audio: wind across the clifftop, surf breaking far below, and her breathing slowing down. No music, no dialogue.",
  "inputs": {
    "referenceImages": [
      "https://example.com/refs/runner.jpg",
      "https://example.com/refs/bottle.jpg",
      "https://example.com/refs/viewpoint.jpg"
    ]
  },
  "width": 1344,
  "height": 768,
  "duration": 8
}
```

- `inputs.referenceImages` takes **up to 9 images**, each up to 16 MB.
- The first image in the list is `<Picture 1>`, the second `<Picture 2>`, and so on. `inputs.referenceVideos` (up to 3) and `inputs.referenceAudios` (up to 3) are numbered separately as `<Video N>` and `<Audio N>`. All references together are capped at **12**.
- `width` and `height` are optional. Without them the output follows the shape of the first reference, covered in [Output shape](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#output-shape).
- References cannot be combined with `inputs.frameImages`. The [image-to-video guide](https://runware.ai/docs/models/heygen-video-1-0/guides/image-to-video) covers opening on a fixed frame instead.

### [Labeling references](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#labeling-references)

Every reference should be **named by its label and by what it is for**: "the trail runner from `<Picture 1>`", "the water bottle from `<Picture 2>`". The label says which image. The role says what the model should take from it.

The hero prompt uses each label twice. The first mention **places the subject in the action**. The second, in a closing sentence, **says exactly what must survive**:

```text
Keep her face, dark bob and freckles exactly as in <Picture 1>, the bottle's forest-green body, bamboo lid and emblem exactly as in <Picture 2>, and the red-and-white lighthouse on the headland exactly as in <Picture 3>.
```

Listing the details to keep turns "use this reference" into a checklist. The emblem and the lid are **small enough to drift** if the prompt only says "the bottle", so they are named.

### [Placing a product](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#placing-a-product)

A single product reference is enough to put a packshot into a scene. **Keep the product still** and let the scene move around it, the same staging that suits a first frame.

[Watch video](https://runware.ai/docs/assets/output-speaker-adaptive.DfdzcNSz.mp4)

*The speaker placed on a balcony table in morning sun*

> **Prompt**: Shot on a large-format cinema camera with a 65mm lens at T2.8, locked off on a tripod at table height. The portable speaker from <Picture 1> stands upright on a weathered teak table on a sunny apartment balcony in the morning, a few potted herbs softly out of focus behind it. Warm sunlight slowly spreads across the table and reaches the speaker from the side, catching the woven fabric. Keep the speaker's terracotta fabric, cream carry strap and single round button exactly as in <Picture 1>. Nothing else moves. No other logos, brand names or printed words anywhere in frame. Audio: birdsong, a light breeze, and a distant city waking up. No music, no dialogue.

**Picture 1**:

![A compact portable speaker in terracotta woven fabric with a cream carry strap and a single round button, on a white background](https://runware.ai/docs/assets/reference-speaker.D1xaZpoP_ZEuEAz.jpg)

> **Prompt**: A photoreal e-commerce packshot of a compact portable wireless speaker wrapped in terracotta woven fabric, with a cream fabric carry strap looped on top and a single round button on the front, standing upright on a plain white background, front three-quarter view, soft even studio light. No logos, brand names or printed words anywhere on the speaker or in frame.

The speaker keeps **its terracotta weave and its cream strap** in a setting it was never photographed in. The clean packshot on white is the right kind of reference for this: nothing in it competes with the product, so there is nothing else for the model to carry over.

### [Keeping a person](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#keeping-a-person)

A portrait reference **keeps a person's identity** in a new scene, which is how a founder or a spokesperson appears across a series of clips without a shoot for each one. Combined with a quoted line, it becomes a talking clip.

[Watch video](https://runware.ai/docs/assets/output-founder.Cjjd6nlk.mp4)

*A product-launch clip from one portrait*

> **Prompt**: Shot on a full-frame mirrorless camera with a 35mm lens at f/2.8, locked off on a tripod at eye level. The man from <Picture 1> sits at a pale wood desk in a bright startup office with plants and a whiteboard softly out of focus behind him. He looks into the camera and says, in a relaxed, confident voice: "We built this for teams who hate status meetings. Your updates write themselves, straight from the work you already do." His lips stay in sync with every word. Keep his face, beard, round tortoiseshell glasses and navy sweater exactly as in <Picture 1>. Soft daylight from a window on the left. Real skin texture, no retouching. No logos, brand names or printed words anywhere in frame, including on the whiteboard. Audio: his voice close and clear over a quiet office room tone. No music.

**Picture 1**:

![A waist-up portrait of a bearded man in round tortoiseshell glasses and a navy crewneck against a plain light-gray wall](https://runware.ai/docs/assets/reference-founder.CPNfbROt_CLNyS.jpg)

> **Prompt**: A photoreal portrait photograph of a software company founder in his late thirties with a close-cropped beard and round tortoiseshell glasses, in a navy crewneck sweater, standing against a plain light-gray wall, waist up, looking into the camera with a calm, friendly expression and his mouth closed. Soft even light, real skin texture. No logos, brand names or printed words anywhere in frame.

The reference was shot standing against a plain wall. The clip **seats him at a desk in an office** the reference never showed, and keeps the glasses and the beard. The [dialogue and sound guide](https://runware.ai/docs/models/heygen-video-1-0/guides/dialogue-and-sound) covers writing and timing the line.

To give a referenced person **a specific voice** rather than one the model picks, pair the portrait with an audio reference, covered in the [audio references guide](https://runware.ai/docs/models/heygen-video-1-0/guides/audio-references).

### [Several views of one product](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#several-views-of-one-product)

One photograph shows one side of a product. When the shot will show more than that, **give the model every side it will see**. The backpack below walks toward the camera and then away from it, so the prompt carries both the outer face and the harness side.

[Watch video](https://runware.ai/docs/assets/output-backpack.BQ0TsIAC.mp4)

*A backpack seen from both sides in one clip*

> **Prompt**: Shot on a large-format cinema camera with a 40mm lens at T4, on a tripod at chest height beside a forest trail. A hiker in her forties in a plain gray fleece walks toward the camera wearing the backpack from <Picture 1> and <Picture 2>, the shoulder straps, mustard sternum buckle and hip belt from <Picture 2> visible across her body. She passes the camera, and the camera pans slowly to follow her as she walks away, showing the outer face of the pack from <Picture 1>: the black roll-top, the front stretch pocket and the mustard zipper pulls. Keep the slate blue fabric and every detail of the backpack exactly as in both references. Dappled morning light through tall pines. No logos, brand names or printed words anywhere in frame. Audio: her boots on the dirt trail, the pack's straps creaking softly, and birdsong in the forest. No music, no dialogue.

**Picture 1: outer face**:

![A slate blue hiking backpack from the outer face, with a black roll-top, front stretch pocket and mustard-yellow zipper pulls, on white](https://runware.ai/docs/assets/reference-backpack-front.o_a331v-_Z3c94U.jpg)

> **Prompt**: A photoreal e-commerce packshot of a 30-liter hiking backpack in slate blue ripstop fabric, seen from the outer face: a black roll-top closure, a large front stretch pocket, two side bottle pockets, and mustard-yellow zipper pulls and buckles. Standing upright on a plain white background, soft even studio light. No logos, brand names or printed words anywhere on the backpack or in frame.

**Picture 2: harness side**:

![The same slate blue backpack from the harness side, showing a charcoal mesh back panel, black shoulder straps and a hip belt with mustard buckles, on white](https://runware.ai/docs/assets/reference-backpack-harness.lb3qmO0D_1CWtxh.jpg)

> **Prompt**: The exact same slate blue hiking backpack, turned around to show the harness side that rests against the wearer: a padded charcoal mesh back panel, two black padded shoulder straps with a mustard-yellow sternum strap buckle, and a padded hip belt with a mustard-yellow buckle. Same fabric, same colors, same roll-top visible at the top. Standing upright on a plain white background, soft even studio light. No logos, brand names or printed words anywhere.

The prompt ties **each view to the moment it is seen**: the harness side while she approaches, the outer face once she has passed. Both labels point at one product, and the closing sentence says so, which stops the model from treating them as two different bags.

### [Output shape](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#output-shape)

Without `width` and `height`, the output **takes the aspect ratio of the first reference image** (or of the first reference video when there are no images). The ratio follows the reference itself, rounded to whole blocks of 32 pixels, rather than snapping to one of the twelve fixed sizes. A 2:3 portrait at 480p, for example, comes back at 480 × 704.

The speaker clip in [Placing a product](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#placing-a-product) came back square because its only reference is a square packshot. The same prompt with `width` 768 and `height` 1344 comes back vertical, whatever the reference's shape:

[Watch video](https://runware.ai/docs/assets/output-speaker-vertical.09dqSrRc.mp4)

*width 768, height 1344: vertical from a square reference*

> **Prompt**: Shot on a large-format cinema camera with a 65mm lens at T2.8, locked off on a tripod at table height. The portable speaker from <Picture 1> stands upright on a weathered teak table on a sunny apartment balcony in the morning, a few potted herbs softly out of focus behind it. Warm sunlight slowly spreads across the table and reaches the speaker from the side, catching the woven fabric. Keep the speaker's terracotta fabric, cream carry strap and single round button exactly as in <Picture 1>. Nothing else moves. No other logos, brand names or printed words anywhere in frame. Audio: birdsong, a light breeze, and a distant city waking up. No music, no dialogue.

Two rules follow. **Put the reference with the right shape first** when you want the output to follow it, since only the first one counts. And **send an explicit size whenever the placement is fixed**, such as a 9:16 story or a 16:9 banner, with `width` and `height`, so the shape never depends on which photo happened to lead the list.

> [!NOTE]
> `resolution` (`480p` or `768p`) is also accepted in reference mode, as an alternative to `width` and `height`. It sets the output size class and keeps the aspect ratio of the first reference.

### [Tips](https://runware.ai/docs/models/heygen-video-1-0/guides/reference-driven-video#tips)

1. **Name each reference by label and role.** "The water bottle from `<Picture 2>`" tells the model which image and what to take from it.
    
2. **Close with what must survive.** A sentence listing the details to keep, per reference, protects the small ones like emblems and glasses.
    
3. **Use clean references.** A product on white or a person against a plain wall gives the model the subject and nothing else to carry over.
    
4. **Give every side the shot will show.** Several views of one product, each tied to the moment it is seen, keep the parts the first photo did not show.
    
5. **Keep the product still.** Let the light or the person around it move. Holding and wearing are the most reliable ways to feature a product.
    
6. **Order the list deliberately.** The first reference decides the output shape when `width` and `height` are left out.
    
7. **Send an explicit size for fixed placements.** With `width` and `height` set, a story slot or a banner never depends on the shape of a reference photo.
    
8. **Use references, not a first frame, for new scenes.** A first frame fixes the opening image. A reference carries the subject into whatever scene the prompt describes.