Heygen Video 1.0 Image To Video API Documentation

Heygen Video 1.0 Image To Video API Documentation

Playground

HeyGen Video 1.0 Image-to-Video animates a starting image into high-quality AI video with prompt-guided motion, automatic aspect-ratio matching, and output up to 2K for creative content, marketing videos, social media, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

HeyGen Video 1.0 Image-to-Video animates a starting image with prompt-guided motion and camera movement. Upload an image, describe how the subject and scene should move, then choose a duration and output resolution up to 2K.

The generated video follows the input image’s aspect ratio, making it suitable for product animation, character motion, creative concepts, and short-form visual storytelling.

Why Choose This?

• Image-to-video generation
  Turn a still image into a prompt-guided video.

• Prompt-guided motion
  Describe subject movement, scene progression, and camera behavior.

• Up to 2K output
  Choose 480p, 768p, 1080p, or 2k.

• Automatic framing
  The generated video follows the aspect ratio of the input image.

• Prompt enhancement
  Choose disabled, turbo, or quality depending on how much prompt enhancement you want.

• Seed control
  Use a fixed seed when comparing prompt or parameter variations.

Parameters

How to Use

1. Upload an image — Provide the starting frame for the video.
2. Describe the motion — Explain how the subject, environment, and camera should move.
3. Set duration — Choose a video length from 5 to 15 seconds.
4. Choose resolution — Select 480p, 768p, 1080p, or 2k.
5. Configure prompt enhancement optional — Use turbo or quality when additional prompt enhancement is useful.
6. Set seed optional — Use a fixed seed when reproducibility is needed.
7. Submit — Generate and retrieve the animated video.

Pricing

Pricing is based on the requested duration and selected resolution.

prompt_enhancement and seed do not add separate charges.

Best Use Cases

• Product animation — Add movement and camera motion to product images.
• Portrait and character animation — Bring people, characters, or illustrations into motion.
• Creative concepts — Animate concept art, campaign visuals, and scene designs.
• Social media content — Turn static assets into short-form video content.
• Visual storytelling — Extend a still composition into a moving scene.
• Promotional videos — Animate marketing and advertising imagery for campaigns.

Pro Tips

• Use a clear source image with the subject and composition already close to the desired result.
• Focus the prompt on motion, action, and camera behavior instead of repeating everything visible in the image.
• Keep the main action clear and consistent with the source image.
• Use 480p for lower-cost testing before moving to higher resolutions.
• Leave prompt_enhancement=disabled when you want the model to follow your original wording more directly.
• Use a fixed seed when comparing prompt or setting changes.

Notes

• image and prompt are required.
• duration supports whole-second values from 5 to 15.
• duration defaults to 5.
• resolution defaults to 768p.
• Output framing follows the input image’s aspect ratio.
• Additional image, video, or audio references are not supported.
• prompt_enhancement defaults to disabled.
• A fixed seed can help compare variations but does not guarantee identical output.

Related Models

• HeyGen Video 1.0 Text-to-Video — Generate videos directly from text prompts.
• HeyGen Video 1.0 Image-to-Video — Animate an input image with prompt-guided motion and camera movement.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "duration": 5,
  "resolution": "768p",
  "prompt_enhancement": "disabled"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/heygen/video-1.0/image-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters