HeyGen Avatar V Serverless API

Studio-quality talking-avatar videos from text or audio.

~142.38s

POST /v2/heygen-avatar-v · 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    "avatar": "Abigail Sofa Front",
11    "prompt": "Hello! This is an Avatar V demo on Segmind.",
12    "voice": "Aaron",
13    "resolution": "1080p",
14    "aspect_ratio": "16:9",
15    "fit": "cover",
16    "caption": False,
17    "output_format": "mp4",
18    "remove_background": False,
19}
20job = client.submit_async("heygen-avatar-v", **payload)
21print(job.request_id)                         # available immediately
22try:
23    result = job.wait(timeout=900, interval=2.0)
24    print(result["status"])                  # COMPLETED
25    print(result.get("output"))              # model output (e.g. video URL)
26except InferenceTimeout as e:
27    print("still running:", e.request_id)    # re-poll later with this id
28except InferenceFailed as e:
29    print("failed:", e.detail)
30
31# Fast models (<=600s) can use the one-liner instead:
32# result = segmind.run("heygen-avatar-v", **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    "avatar": "Abigail Sofa Front",
11    "prompt": "Hello! This is an Avatar V demo on Segmind.",
12    "voice": "Aaron",
13    "resolution": "1080p",
14    "aspect_ratio": "16:9",
15    "fit": "cover",
16    "caption": False,
17    "output_format": "mp4",
18    "remove_background": False,
19}
20job = client.submit_async("heygen-avatar-v", **payload)
21print(job.request_id)                         # available immediately
22try:
23    result = job.wait(timeout=900, interval=2.0)
24    print(result["status"])                  # COMPLETED
25    print(result.get("output"))              # model output (e.g. video URL)
26except InferenceTimeout as e:
27    print("still running:", e.request_id)    # re-poll later with this id
28except InferenceFailed as e:
29    print("failed:", e.detail)
30
31# Fast models (<=600s) can use the one-liner instead:
32# result = segmind.run("heygen-avatar-v", **payload)

API Endpoint

POSThttps://api.segmind.com/v1/heygen-avatar-v

Parameters

aspect_ratiooptional

string

Output aspect ratio. Use 16:9 for landing pages, 9:16 for shorts/reels, 1:1 for social feed.

Default: "16:9"

Allowed values :

"16:9""9:16""4:5""5:4""1:1""auto"

audio_urloptional

string (uri)

Public MP3/WAV URL to lip-sync to instead of prompt+voice. Use for music videos or pre-recorded narration.

avataroptional

string

Choose a ready-made HeyGen Digital Twin avatar (24 options). Use defaults for product demos or pitches.

Default: "Abigail Sofa Front"

Allowed values (24 total):

"Abigail Sofa Front""Amelia Business Training Front""Anja Office Front""Ann Doctor Sitting""Annie Bar Sitting Front""Artur Office Front""Aubrey Night Scene Front""Blanka Lounge Front""Bojan Business Training Front""Brandon Business Sitting Front"+14 more

avatar_idoptional

string

Raw HeyGen avatar ID; overrides 'avatar'. Pass a Digital Twin ID from heygen-avatar-v-create for custom faces.

backgroundoptional

string

Optional background — hex color (#FFFFFF) or image URL. Leave blank for the avatar's native scene.

captionoptional

boolean

Generate SRT captions; response becomes JSON with video_url + caption_url. Enable for accessibility or social posts.

Default: false

fitoptional

string

How the avatar fits the frame. 'cover' fills the frame (recommended); 'contain' preserves entire framing.

Default: "cover"

Allowed values :

"cover""contain"

output_formatoptional

string

Output container — mp4 for standard playback, webm to preserve transparent background channel.

Default: "mp4"

Allowed values :

"mp4""webm"

promptoptional

string

Text the avatar will speak; mutually exclusive with audio_url. Keep clips under 60s for fastest renders.

remove_backgroundoptional

boolean

Strip background for compositing into other scenes. Pair with output_format=webm for alpha channel.

Default: false

resolutionoptional

string

Output resolution: 720p (cheap drafts), 1080p (default — best quality/cost), 4k (premium production).

Default: "1080p"

Allowed values :

"720p""1080p""4k"

video_urloptional

string (uri)

Reference footage (≥15s, video/mp4) to train a Digital Twin in one call. Adds $1.25 one-time training fee.

voiceoptional

string

Text-to-speech voice paired with prompt. Match voice tone to use case — Aaron and Daniel suit explainers.

Default: "Aaron"

Allowed values (20 total):

"Aaron""Allison""AstroMesh""Blanka - Lifelike""Camden""Chill Brian""Daniel""Elio""Ida - Lifelike""Jessica Anne Bogart"+10 more

voice_idoptional

string

Raw HeyGen voice ID; overrides 'voice'. Use for cloned or premium voices beyond the dropdown list.

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-avatar-v
Submit — returns request_id, status_url, response_url
2
GET /v2/requests/{id}/status
Poll — until COMPLETED or FAILED
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