Heygen Video 1.0 Reference To Video API Documentation

Heygen Video 1.0 Reference To Video API Documentation

Playground

HeyGen Video 1.0 Reference-to-Video generates high-quality AI videos guided by image, video, and optional audio references, with prompt-controlled scenes and output up to 2K for character consistency, product videos, social content, marketing creatives, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

HeyGen Video 1.0 Reference-to-Video creates short videos using images and videos as visual references. Add a prompt to describe the scene, motion, camera direction, dialogue, and sound, with optional audio references for additional guidance.

Why Choose This?

• Flexible visual references — Use images and videos to guide people, products, environments, and visual style.
• Multi-reference workflows — Combine multiple images and videos in a single generation.
• Optional audio references — Add audio to guide voices, dialogue, or soundtrack direction.
• Up to 2K output — Choose 480p, 768p, 1080p, or 2k.
• Prompt control — Describe scene progression, movement, camera behavior, dialogue, and sound.

Parameters

A maximum of 12 reference files can be used in one request. At least one image or video reference is required.

How to Use

1. Add visual references — Supply at least one image or video.
2. Write a prompt — Describe the scene and explain how the references should be used.
3. Add audio optional — Include audio references when voice or soundtrack guidance is needed.
4. Choose output settings — Set duration, resolution, and aspect ratio.
5. Submit — Generate and retrieve the completed video.

Pricing

Pricing is based on the duration, resolution, reference video duration, and number of reference images.

The first 2 reference images are included. Each additional reference image costs $0.04.

Examples at 768p

Audio references, prompt_enhancement, and seed do not add separate charges.

Best Use Cases

• Product videos — Generate scenes using your own product references.
• Character consistency — Guide recurring people or characters with reference images.
• Location-based scenes — Use visual references to establish environments and settings.
• Multi-reference storytelling — Combine several visual materials into a new scene.
• Dialogue-driven clips — Add audio references alongside visual guidance.
• Creative campaigns — Build promotional videos from existing brand assets.

Pro Tips

• Use clear references and explain the role of each one in the prompt.
• Refer to images as <Picture 1>, <Picture 2>, and so on according to their order.
• Refer to audio as <Audio 1>, <Audio 2>, and so on.
• Keep the main action and dialogue focused.
• Start with fewer references when testing a new concept.
• Use lower resolution for faster, lower-cost iteration before generating higher-resolution results.

Notes

• At least one image or video reference is required. Audio-only requests are not supported.
• Supports up to 9 images, 3 videos, and 3 audio clips, with no more than 12 reference files total.
• Empty reference arrays are treated as omitted.
• Each reference image must be no larger than 16 MiB.
• Each reference video or audio file must be no larger than 32 MiB.
• Only the first 5 seconds of each reference video are used.
• References guide the generated scene but do not lock the first frame.
• Supported aspect ratios are 16:9 and 9:16.
• Custom pixel dimensions and a separate first-frame image are not supported.
• Actual output duration may vary slightly from the requested duration.
• A fixed seed can help compare variations but does not guarantee identical results.

Related Models

• HeyGen Video 1.0 Text-to-Video — Generate videos directly from text prompts.
• HeyGen Video 1.0 Image-to-Video — Animate a starting image with prompt-guided motion.

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'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "16:9",
  "prompt_enhancement": "disabled",
  "reference_images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ]
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/heygen/video-1.0/reference-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

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. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

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

Parameters

Task Submission Parameters

Request Parameters

Conditional constraints

• Not allowed: reference_images has at most 0 items or omitted and reference_videos has at most 0 items or omitted.
• Not allowed: reference_audios has at least 3 items and reference_images has at least 9 items and reference_videos has at least 1 items.
• Not allowed: reference_audios has at least 2 items and reference_images has at least 9 items and reference_videos has at least 2 items.
• Not allowed: reference_audios has at least 3 items and reference_images has at least 8 items and reference_videos has at least 2 items.
• Not allowed: reference_audios has at least 1 items and reference_images has at least 9 items and reference_videos has at least 3 items.
• Not allowed: reference_audios has at least 2 items and reference_images has at least 8 items and reference_videos has at least 3 items.
• Not allowed: reference_audios has at least 3 items and reference_images has at least 7 items and reference_videos has at least 3 items.

Response Parameters

Result Request Parameters

Result Response Parameters