by HeyGen

2K Video

heygen/video-1/image-to-video
  • Up to 2K
  • 5–15s clips
  • Create Video
  • Image to Video
  • Reference to Video

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.

ParameterWhat to supply
image_urlThe source photo that defines the person and composition.
promptThe action, camera behavior, lighting, and scene direction.
duration_secondsA requested output duration from 5 to 15 seconds.
resolution480p, 768p, 1080p, or 2k; use lowercase 2k in JSON.
prompt_optimization_modedisabled avoids a rewrite; turbo and quality allow one.
seedA 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.

  1. Select a photo with the person and setting you want to retain.
  2. Write one motion instruction and state which visual elements matter.
  3. Review a 480p trial for the person's appearance and the action.
  4. 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 tierMeasured output
480p832×480
1080p1890×1080
2k2688×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

ParameterRequiredDescription
duration_secondsNoLength of the generated clip. ≥ 5 · ≤ 15 · Default: 5
image_urlYesThe picture to start from.
promptYesDescribe what you want to make.
prompt_optimization_modeNoHow your prompt gets rewritten: one quick pass, or a more detailed multi-step rewrite. disabled · turbo · quality · Default: disabled
resolutionNoChoose an available output size. 480p · 768p · 1080p · 2k · Default: 768p
seedNoUse 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.

OptionUSD 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

  1. 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.
  2. 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.
  3. 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.

More about HeyGen Video 1.0