HeyGen Video API
Text, image or reference to video with native audio.
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) 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
https://api.segmind.com/v1/heygen-video-1Parameters
promptrequiredstringDescribe 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).
"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_ratiooptionalstringauto: 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.
"auto""auto""21:9""16:9""4:3""1:1""3:4""9:16"durationoptionalintegerVideo 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.
5Range: 5 - 30imageoptionalstring (uri)Optional first frame: the clip opens exactly on this image and keeps its shape (image to video). Cannot be combined with references.
prompt_enhancementoptionalstringHow the prompt is expanded before generation: turbo is fastest, quality is balanced, ultraquality is slowest and best, disabled sends your prompt as written.
"quality""turbo""quality""ultraquality""disabled"reference_audiooptionalstring[]Optional, up to 3 audio files (<Audio 1> ...); needs a reference image or video too.
reference_imagesoptionalstring[]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_videosoptionalstring[]Optional, up to 3 clips (<Video 1> ...). Only the first 5 seconds of each are read.
resolutionoptionalstringOutput resolution. 1080p and 2k render in 16:9 or 9:16 only and cost more per second.
"768p""480p""768p""1080p""2k"seedoptionalintegerFix the seed to repeat a shot; the same prompt and seed return the same clip. Empty = random.
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
POST /v2/heygen-video-1Submit — returns request_id, status_url, response_url
- 2
GET /v2/requests/{id}/statusPoll — until COMPLETED or FAILED
- 3
GET /v2/requests/{id}Result — final response body
Status states
- 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.
Bad Request
Invalid parameters or request format
Unauthorized
Missing or invalid API key
Forbidden
Insufficient permissions
Not Found
Model or endpoint not found
Insufficient Credits
Not enough credits to process request
Rate Limited
Too many requests
Server Error
Internal server error
Bad Gateway
Service temporarily unavailable
Timeout
Request timed out