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/image-to-video on POST /jobs/createTask, from $0.14.
Introduction
HeyGen Video 1.0 API for image to video
HeyGen Video 1.0 animates a supplied photo for 5–15 seconds, with native 480p, 768p, 1080p, and 2k tiers. Our image tests retained the source person and composition, so this endpoint is a practical starting point when the photograph already defines the shot.
Send the photo and its movement
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}Use a photograph and likeness you have the right to use.
Collect the returned video
The submission returns a task ID that you use to retrieve the result with GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}Save the returned asset and compare the moving person and framing against the input photograph.
Set the animation parameters
Pass image_url alongside the prompt, then choose duration and a native resolution tier. The settings below intentionally separate the photo input from the movement you want the model to add.
| Parameter | What to supply |
|---|---|
image_url | The source photo that defines the person and composition. |
prompt | The action, camera behavior, lighting, and scene direction. |
duration_seconds | A requested output duration from 5 to 15 seconds. |
resolution | 480p, 768p, 1080p, or 2k; use lowercase 2k in JSON. |
prompt_optimization_mode | disabled avoids a rewrite; turbo and quality allow one. |
seed | A comparison control for revisions, without an identical-result promise. |
Preserve what the photograph establishes
Describe a small change from the source pose rather than rebuilding the whole scene in words. A head turn or a glance gives you a clear action to judge while comparing the person and framing against the still.
HeyGen says that image-to-video opens on the supplied picture. Those are publisher descriptions; our evidence here is the photo continuity and native dimensions recorded in the supplied tests.
- Select a photo with the person and setting you want to retain.
- Write one motion instruction and state which visual elements matter.
- Review a 480p trial for the person's appearance and the action.
- Try 1080p or 2k after the scene direction is useful, holding the seed fixed for comparison.
Compare our measured sizes
Our five-second photo tests produced native outputs at the requested tiers and kept the source person. These measurements describe the tested source composition, rather than a universal pixel map for every photograph.
| Requested tier | Measured output |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
768p is also supported, but we have no image-test dimensions for that tier to report. We have no image-specific processing-time measurement either, so the text run's roughly 10 seconds should not be treated as this endpoint's timing estimate.
Check input problems and alternatives
Check image_url, the prompt, and the resolution spelling when a request is rejected. Keep duration within 5–15 seconds and use 2k for that tier; consult the current schema and any returned task error before changing fields. A result that changes an important gesture needs visual review even when the task succeeded.
Choose text-to-video when you want a scene from words without a source photo. Choose reference-to-video to assign a portrait and product separate roles, while remembering that its video inputs can dominate identity. For a photo intended to speak as an avatar, review HeyGen Avatar IV instead.
Request parameters
| Parameter | Required | Description |
|---|---|---|
duration_seconds | No | Length of the generated clip. ≥ 5 · ≤ 15 · Default: 5 |
image_url | Yes | The picture to start from. |
prompt | Yes | Describe what you want to make. |
prompt_optimization_mode | No | How your prompt gets rewritten: one quick pass, or a more detailed multi-step rewrite. disabled · turbo · quality · Default: disabled |
resolution | No | Choose an available output size. 480p · 768p · 1080p · 2k · Default: 768p |
seed | No | Use the same seed and settings for more controlled comparisons. ≥ 0 · ≤ 2147483647 |
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 |
| resolution 1080p | $0.135 |
| resolution 2K | $0.135 |
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/image-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/image-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
"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 Image to Video, its lowest-priced task. Prices by option: 480p $0.028 per second, 768p $0.051 per second, 1080p $0.135 per second, 2K $0.135 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 are the limits of the HeyGen Video 1.0 · Image to Video API?
Clip length: 5–15 s; Resolutions: 480p · 768p · 1080p · 2K; Prompt length (characters): 32,000; Largest upload: 16 MB. Requests outside these limits are rejected before anything is charged.