About HeyGen Video 1.0
HeyGen Video 1.0 is HeyGen's scene-generation model. It makes 5 to 15 second clips from a written brief, from a starting photo, or from a mix of reference images, videos and audio. Clips from text come with a stereo soundtrack at 480p or 768p; a photo can go up to 1080p or 2K.
Call it with the model name heygen/video-1/text-to-video on POST /jobs/createTask, from $0.14.
Introduction
HeyGen Video 1.0 API for text to video
HeyGen Video 1.0 turns a written scene into a 5–15 second clip at 480p or 768p with an AAC stereo audio track. This endpoint needs a prompt rather than an image, making it suitable for a concept shot before you have photography or footage.
Submit a scene request
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}Retrieve the task response
Read data.taskId from the submission response, then query GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID with your Bearer key. A successful result exposes the generated asset URL; the examples here omit unrelated response fields and use placeholder IDs and URLs.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}See the task API guide for the complete request and response contract. Opening an asset URL lets you review the picture and listen to the generated track.
Choose the scene controls
Use the following controls to specify duration, picture size, and how the prompt is handled. Select an aspect ratio from the endpoint's current options when the delivery format matters.
| Parameter | Purpose and supported settings |
|---|---|
prompt | Describe the subject, visible action, setting, light, and intended sound. |
duration_seconds | Request 5–15 seconds of output. |
resolution | Choose 480p or 768p; this endpoint has no 1080p tier. |
aspect_ratio | Select a supported frame shape in the current endpoint controls. |
prompt_optimization_mode | disabled, turbo, or quality; the latter two allow a rewrite. |
seed | Keep fixed when comparing a single prompt revision; identical output is not guaranteed. |
Direct a contained shot
Give one visible action a clear setting before adding camera instructions. For example, describe a person turning toward a shelf rather than asking for a room tour, a gesture, and a scene change in the same short clip.
HeyGen says to name the camera setup, lighting, and sound sources in the brief. Its guidance favors contained scenes and notes limitations around intricate hand movements and long on-screen copy. Treat that as publisher guidance, and review your own footage for those details.
- Name the person, clothing, place, and action in that order.
- Add a specific view, such as a static medium shot with window light.
- Describe the sounds you want; specify no music when appropriate.
- Compare a revision with the same seed and rewrite mode before changing other settings.
Read the measured result
Our neutral text test requested five seconds at 480p and returned 832×480 video at 24 fps with AAC stereo audio. Processing took about 10 seconds in that run; it does not establish a typical completion time for every scene.
Five-second requests across the supplied tests produced 5.18–5.26 second files, rounded to whole frames. If a timeline needs an exact edit point, inspect the file duration and trim it in your editor.
Resolve limits and choose another task
Keep the request within 5–15 seconds and select 480p or 768p before submitting. For an input error, compare the field names and resolution against the table and the current schema; for a failed task, inspect its errorCode and errorMessage rather than treating an unfinished task as a completed video.
Use image-to-video when a particular photo should guide the person and composition or when you need native 1080p or 2k. Use reference-to-video for separately supplied people, products, or motion references. A talking photo belongs in HeyGen Avatar IV; a translation task belongs in HeyGen Video Translate.
Request parameters
| Parameter | Required | Description |
|---|---|---|
seed | No | Use the same seed and settings for more controlled comparisons. ≥ 0 · ≤ 2147483647 |
prompt | Yes | Describe what you want to make. |
resolution | No | Choose an available output size. 480p · 768p · Default: 768p |
aspect_ratio | No | The shape of the frame: wide, square or tall. 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9 · Default: 16:9 |
duration_seconds | No | Length of the generated clip. ≥ 5 · ≤ 15 · Default: 5 |
prompt_optimization_mode | No | How your prompt gets rewritten: one quick pass, or a more detailed multi-step rewrite. disabled · turbo · quality · Default: disabled |
Pricing
Prices are in USD and charged to your PopNow balance. When a task is accepted, we reserve the maximum quoted amount from your API balance. On completion, we charge for actual usage, never more than the hold, and release the remainder. If the task fails, the hold is released.
| Option | USD per second |
|---|---|
| resolution 480p | $0.028 |
| resolution 768p | $0.051 |
Send the same request body to POST /jobs/quote to see the estimated and maximum USD charge before running. A quote does not run the task or charge your balance.
API quick start
Call the HeyGen Video 1.0 API in three steps
- Create an API key. Sign in to PopNow and create a key in the API console. Keys start with sk-popnow-. API calls are billed in USD from your PopNow balance.
- Send the request. POST /jobs/createTask with model heygen/video-1/text-to-video and an input object that follows the parameter table. The response returns a task ID straight away.
- Get the result. Poll GET /jobs/recordInfo with the task ID, or pass a callBackUrl and we post the result to it. Download the output links when the task succeeds.
# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $POPNOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"aspect_ratio": "16:9",
"resolution": "768p",
"duration_seconds": 5
}
}'
# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $POPNOW_API_KEY"Replace the prompt and any links with your own. The API tab has the response, polling and callback reference.
HeyGen Video 1.0 API questions
How much does the HeyGen Video 1.0 API cost?
HeyGen Video 1.0 starts at $0.14 for a 5-second clip with Create Video, its lowest-priced task. Prices by option: 480p $0.028 per second, 768p $0.051 per second. API usage is charged in USD to your PopNow balance. When a task is accepted, we reserve the maximum quoted amount from your API balance. On completion, we charge for actual usage, never more than the hold, and release the remainder. If the task fails, the hold is released.
What is the model name for HeyGen Video 1.0 in the API?
Put heygen/video-1/text-to-video for Create Video; heygen/video-1/image-to-video for Image to Video; heygen/video-1/reference-to-video for Reference to Video in the model field of POST /jobs/createTask.
How do I call the HeyGen Video 1.0 API?
Submit a task using the public endpoint name and an input object containing prompt and your chosen settings. For example, use heygen/video-1/text-to-video with duration_seconds set to 5 and resolution set to 480p. The endpoint guides below show the JSON body and how to retrieve the task result.
Should I use text, image, or reference to video?
Use text for a scene described in words, image for animating a supplied photo, and references for combining separately supplied material. Image-to-video kept the source person and composition in our tests. Reference-to-video used both a portrait and a product image, but a video reference dominated the face in a mixed-input test.
Does text-to-video include an audio track?
Text-to-video includes AAC stereo audio with the generated picture. Our five-second 480p test returned an audio-bearing 832×480 clip at 24 fps. HeyGen says to describe the intended ambience and sound effects in the prompt, and to specify no music when that is your preference.
How do I refer to uploaded pictures, video, and audio?
Name reference items in the prompt using <Picture 1>, <Video 1>, and <Audio 1>. HeyGen’s documentation says that each media type has its own numbering based on list order. Assign each item a role, such as the person in <Picture 1> holding the bottle in <Picture 2>.
Why did a reference video replace the person from my photo?
A dominant reference video can outweigh a portrait’s identity cues, as our mixed-reference test showed. With one image, a four-second video, and audio, the result followed the video’s scene and motion closely without carrying over the image’s face. Avoid a dominant video when the person from the photo is the priority, or use image-to-video for that photo.
What are the limits of the HeyGen Video 1.0 API?
Clip length: 5–15 s; Resolutions: 480p · 768p; Aspect ratios: 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9; Prompt length (characters): 32,000. Requests outside these limits are rejected before anything is charged.
Can I try HeyGen Video 1.0 without writing code?
Run HeyGen Video 1.0 in the Playground with your API USD balance, without an API key. Each run appears in your developer history with its matching code.
All HeyGen models
MiniMax H3 is the default video model on PopNow and also starts from text, a photo or references. Choose HeyGen Video 1.0 when you want 2K from a photo or its own look.
- HeyGen Avatar 6 APIA portrait speaks your recording at 1080p or 2K with gestures that follow the script, up to 10 minutesFrom $0.12 per second
- HeyGen Avatar 6 Turbo APIFaster Avatar 6 talking video at 1080p or 2K from a portrait and a voice, up to 10 minutesFrom $0.06 per second
- HeyGen Avatar IV APIA portrait speaks your recording for up to 10 minutes, with an optional new backgroundFrom $0.051 per second
- HeyGen Video 1.0 API5–15-second clips from text with sound, from a photo up to 2K, or from mixed referencesFrom $0.14 for a 5-second clip
- HeyGen Video Translate APIDub a video into 178 languages and dialects with matching lipsFrom $0.045 per second