Heygen Video 1.0 Text To Video API Documentation

Heygen Video 1.0 Text To Video API Documentation

Playground

HeyGen Video 1.0 Text-to-Video generates short AI videos from text prompts with duration control, optional prompt enhancement, and seed settings 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 Text-to-Video generates short videos directly from text prompts. Describe the subject, setting, action, camera movement, and visual direction, then choose the duration, resolution, and aspect ratio for the final clip.

It supports 480p and 768p output with durations from 5 to 15 seconds, making it suitable for social content, creative concepts, promotional clips, and visual storytelling.

Why Choose This?

• Text-to-video generation
  Create videos directly from natural-language scene descriptions.

• 480p and 768p output
  Choose the resolution that fits your quality and cost requirements.

• Multiple aspect ratios
  Generate landscape, portrait, square, and ultrawide video layouts.

• Flexible duration
  Generate clips from 5 to 15 seconds.

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

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

Parameters

How to Use

1. Write a prompt — Describe the subject, setting, action, camera movement, and visual style.
2. Set duration — Choose a length from 5 to 15 seconds.
3. Choose resolution — Select 480p or 768p.
4. Choose aspect ratio — Select the layout that fits your target content.
5. Configure prompt enhancement optional — Use turbo or quality when you want additional prompt expansion.
6. Set seed optional — Use a fixed seed when reproducibility is useful.
7. Submit — Generate and retrieve the completed video.

Pricing

Pricing is based on the requested duration and selected resolution.

Example Costs

aspect_ratio, prompt_enhancement, and seed do not add separate charges.

Best Use Cases

• Social media videos — Create short-form visual stories and promotional clips.
• Creative concepts — Explore scene ideas, visual styles, and camera directions.
• Advertising content — Generate short campaign and product-focused video concepts.
• Visual storytelling — Turn written scene descriptions into motion.
• Presentation content — Create short supporting visuals for pitches and presentations.
• Rapid video prototyping — Test different prompts, framing, and motion ideas quickly.

Pro Tips

• Keep the main subject and action clear.
• Describe camera movement explicitly when it matters.
• Include lighting, environment, mood, and visual style when they are important to the result.
• Use 480p for lower-cost iteration before moving to 768p.
• 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

• prompt is required.
• duration supports whole-second values from 5 to 15.
• duration defaults to 5.
• resolution defaults to 768p.
• aspect_ratio defaults to 16:9.
• prompt_enhancement defaults to disabled.

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.

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"
}
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/text-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