HeyGen Video API

Text, image or reference to video with native audio.

PlaygroundAPI
Pricing
~29.89s
POST /v2/heygen-video-1 · submit + poll
 1# pip install "segmind>=1.1.0"
 2# export SEGMIND_API_KEY="YOUR_API_KEY"
 3from segmind import SegmindClient, InferenceFailed, InferenceTimeout
 4
 5# Async (v2) — recommended for long-running / video models.
 6# run() blocks up to 600s; submit_async + job.wait(timeout=...) sets a longer
 7# deadline and keeps the request_id so you can re-poll later.
 8client = SegmindClient()                      # reads SEGMIND_API_KEY
 9payload = {
10    "prompt": "A cheesemonger in her fifties, in a navy-and-white striped apron over a grey shirt, stands behind a worn wooden counter stacked with wheels of aged cheese in a small corner shop. Locked-off camera on a tripod, a medium shot framing her from the waist up, no camera movement. Daylight falls through the shopfront window to her left. She lifts one pale wedge of cheese toward the lens, holds it steady, and says to camera: \"This one's aged eighteen months. Taste it.\" Visible skin texture, pores and fine lines on her face and hands; no retouching, no beauty filter, no glamour lighting. Muted colour, no teal-orange grade. Plain apron and shelving, no logos, brand names, printed words or badges anywhere in frame. Sound: her voice close and clear, a short knife tap against the hard rind, a doorbell jingling once in the background, the low murmur of a few customers further back. No music.",
11    "resolution": "768p",
12    "duration": 8,
13    "aspect_ratio": "auto",
14    "prompt_enhancement": "quality",
15}
16job = client.submit_async("heygen-video-1", **payload)
17print(job.request_id)                         # available immediately
18try:
19    result = job.wait(timeout=900, interval=2.0)
20    print(result["status"])                  # COMPLETED
21    print(result.get("output"))              # model output (e.g. video URL)
22except InferenceTimeout as e:
23    print("still running:", e.request_id)    # re-poll later with this id
24except InferenceFailed as e:
25    print("failed:", e.detail)
26
27# Fast models (<=600s) can use the one-liner instead:
28# result = segmind.run("heygen-video-1", **payload)

API Endpoint

POSThttps://api.segmind.com/v1/heygen-video-1

Parameters

promptrequired
string

Describe the shot: subject, setting, camera, light and sound; quote any spoken line. With references, name them <Picture 1>, <Video 1>, <Audio 1> in list order. Long, specific prompts work best (up to 32,000 characters).

Default: "A plant supervisor in a plain grey coat stands beside a conveyor line, locked-off camera, and says to camera: \"Every harness gets checked before the shift starts.\" Machine hum and distant clatter."
aspect_ratiooptional
string

auto: 16:9 for text, the reference's shape with references; a first frame always keeps its own shape. 1080p and 2k need 16:9 or 9:16.

Default: "auto"
Allowed values :
"auto""21:9""16:9""4:3""1:1""3:4""9:16"
durationoptional
integer

Video length in whole seconds: 5-30 for text or a first frame (over 15 s needs prompt enhancement turbo or quality), 5-15 with references. Billed per second.

Default: 5Range: 5 - 30
imageoptional
string (uri)

Optional first frame: the clip opens exactly on this image and keeps its shape (image to video). Cannot be combined with references.

prompt_enhancementoptional
string

How the prompt is expanded before generation: turbo is fastest, quality is balanced, ultraquality is slowest and best, disabled sends your prompt as written.

Default: "quality"
Allowed values :
"turbo""quality""ultraquality""disabled"
reference_audiooptional
string[]

Optional, up to 3 audio files (<Audio 1> ...); needs a reference image or video too.

reference_imagesoptional
string[]

Optional, up to 9 images of people, products or places to keep in a new scene (reference to video, up to 15 s). Address them as <Picture 1>, <Picture 2> ...

reference_videosoptional
string[]

Optional, up to 3 clips (<Video 1> ...). Only the first 5 seconds of each are read.

resolutionoptional
string

Output resolution. 1080p and 2k render in 16:9 or 9:16 only and cost more per second.

Default: "768p"
Allowed values :
"480p""768p""1080p""2k"
seedoptional
integer

Fix the seed to repeat a shot; the same prompt and seed return the same clip. Empty = random.

Range: 0 - 4294967295

Response Type

Returns: Video

Asynchronous requests (v2)

Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.

  1. 1
    POST /v2/heygen-video-1

    Submit — returns request_id, status_url, response_url

  2. 2
    GET /v2/requests/{id}/status

    Poll — until COMPLETED or FAILED

  3. 3
    GET /v2/requests/{id}

    Result — final response body

Status states

QUEUED— Accepted, waiting for a worker
PROCESSING— Running on a worker
COMPLETED— Done — result body is ready
FAILED— Errored (incl. content/RAI blocks)
  • A FAILED request is served as HTTP 422 — the body still carries the error detail.
  • An unknown or expired request_id returns HTTP 404.
  • Results are retained for 1 hour, then expire.
  • Content / RAI blocks surface as FAILED, not a separate state.
  • Track completion by polling the status endpoint.

Common Error Codes

The API returns standard HTTP status codes. Detailed error messages are provided in the response body.

400

Bad Request

Invalid parameters or request format

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Model or endpoint not found

406

Insufficient Credits

Not enough credits to process request

429

Rate Limited

Too many requests

500

Server Error

Internal server error

502

Bad Gateway

Service temporarily unavailable

504

Timeout

Request timed out