HeyGen Video 1 Reference to Video overview
HeyGen Video 1 Reference to Video by HeyGen
HeyGen Video 1 generates video from text, images or references at resolutions from 480p to 2K. This endpoint builds a 5 to 15 second clip with sound from up to 9 reference images and a prompt.
HeyGen Video 1 Reference to Video specs
- Model ID
heygen/video-1-reference-to-video- Developer
- HeyGen
- Input
- Image
- Output
- Video
- Endpoint
POST https://api.aimlapi.com/v2/video/generations
References carry the subject, the prompt carries the scene
HeyGen describes reference to video as creating a new scene that preserves supplied people, products or places based on a prompt and reference media. HeyGen also says the model uses the references to maintain the identity or characteristics of the supplied subjects in the generated scene.
Let the images show who or what appears and use the prompt for the action and the setting. Check the first clip against your references for identity details before you change any other setting.
Settings to tune first
Aspect ratio set to adaptive follows the references. HeyGen says the default uses the ratio of the first reference image, so put the image with the framing you want first. Resolution runs from 480p to 2k, and duration runs from 5 to 15 seconds.
Prompt enhancement sets how much HeyGen rewrites your prompt before generation. Ultraquality and disabled limit the duration to 15 seconds. Start with quality, and compare it against disabled when you want the prompt followed as written. Run a 5 second clip at 480p first, then raise resolution and duration once the subjects match your references.
Use cases
Show a product from your photos in a new setting for a short ad clip.
Keep a character from your reference images consistent across several generated scenes.
Put a person from a portrait into a scene that a prompt describes.
Apply the look of a style reference to a new short video with sound.
HeyGen Video 1 Reference to Video API pricing
| Usage | Price | Unit |
|---|---|---|
| Video generation | $0.035 |
Prices from the AI/ML API price list, checked on Nov 12, 2026.
How to use the HeyGen Video 1 Reference to Video API
View docs
Build with your agent
Give your agent the model details, code and documentation.
1Get your API key
Create API keyexport AIMLAPI_KEY="8f2b4c7d9a1e6b3f…"2Make your first request
curl 'https://api.aimlapi.com/v2/video/generations' \
-H "Authorization: Bearer $AIMLAPI_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "heygen/video-1-reference-to-video",
"prompt": "A slow dolly shot through a sunlit greenhouse full of ferns, light dust in the air, natural camera motion",
"image_urls": [
"https://example.com/input.jpg"
]
}'import os
import requests
headers = {
"Authorization": f"Bearer {os.environ['AIMLAPI_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "heygen/video-1-reference-to-video",
"prompt": "A slow dolly shot through a sunlit greenhouse full of ferns, light dust in the air, natural camera motion",
"image_urls": [
"https://example.com/input.jpg"
]
}
response = requests.post("https://api.aimlapi.com/v2/video/generations", headers=headers, json=payload, timeout=120)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.aimlapi.com/v2/video/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AIMLAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "heygen/video-1-reference-to-video",
"prompt": "A slow dolly shot through a sunlit greenhouse full of ferns, light dust in the air, natural camera motion",
"image_urls": [
"https://example.com/input.jpg"
]
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());The request returns a generation id. Poll GET https://api.aimlapi.com/v2/video/generations?generation_id=<id> until the status is completed.
Models similar to HeyGen Video 1 Reference to Video
HeyGen Video 1 Reference to Video FAQ
How much does HeyGen Video 1 Reference to Video cost?
HeyGen Video 1 Reference to Video costs $0.035 / sec on AI/ML API.
What can I use as references?
You can supply up to 9 reference images of people, objects or style. The prompt then guides what happens in the scene.
Which aspect ratios work at 1080p and 2k?
HeyGen states that reference to video supports 16:9 or 9:16 at 1080p and 2K. Other ratios such as 1:1 or 4:3 are for lower resolutions.
How long can a clip be?
Duration is set in whole seconds from 5 to 15. The endpoint does not return clips longer than 15 seconds.
Can I stop HeyGen from rewriting my prompt?
Set prompt enhancement to disabled to send the prompt as written. Turbo, quality and ultraquality rewrite it to different degrees.
What is the HeyGen Video 1 Reference to Video model ID?
Use heygen/video-1-reference-to-video as the model parameter. Requests go to https://api.aimlapi.com/v2/video/generations with your AI/ML API key.