heygen/heygen-avatar4/image-to-video
Heygen Avatar4 is HeyGen's image-to-video AI model. Bring static images to life with fluid animation, consistent character motion, and professional-grade video output.
PNG, JPEG, WebP, or GIF · 20 MiB maximum
Example output — click Run to generate your own
Send your first request
OpenAI-compatible endpoint with unified authentication and usage tracking.
https://api.sandbase.ai/v1/runheygen/heygen-avatar4/image-to-videoInput Schema
7 parameters · 1 required · 6 optional
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Required | URL of the image to animate. The image should contain a clear face. |
audio | string | Optional | URL of an audio file for the avatar to lip-sync to. When provided, overrides prompt and voice. |
voice | string | Optional | The voice ID to use for the avatar. · Default: "Melissa" |
prompt | string | Optional | The text the avatar will speak |
resolution | string | Optional | Video resolution preset. · Options: 360p, 480p, 540p, 720p, 1080p · Default: "720p" 360p480p540p720p1080p |
aspect_ratio | string | Optional | Aspect ratio of the output video. 'auto' preserves the source aspect ratio when available. · Options: 16:9, 9:16, 4:5, 5:4, 1:1, auto · Default: "16:9" 16:99:164:55:41:1auto |
talking_style | string | Optional | Talking style: 'stable' for minimal movement, 'expressive' for more animation. · Options: stable, expressive · Default: "stable" stableexpressive |
Output Schema
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the generation task |
status | string | Task status: pending, running, completed, failed, timeout |
model | string | Model used for the generation |
outputs | array | Array of output items |
outputs[].url | string | URL of the generated artifact |
outputs[].content_type | string | MIME type (e.g. image/png, video/mp4) |
error | object | null | Error details if failed, null on success |
error.type | string | Machine-readable error type code |
error.message | string | Human-readable error description |
Async Workflow
This model uses asynchronous execution. Submit a request and poll for the result.
- Submit — POST to /v1/run, receive an
id - Poll — GET /v1/run/{id} until status is
completed,failed, ortimeout - Retrieve — Read
outputsfrom the completed response
Code Examples
Ready-to-run snippets
# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "heygen/heygen-avatar4/image-to-video",
"image": "https://v3b.fal.media/files/b/0a90062c/A7EIviZqNxZ2HAs0yHeZ6_77a05b99-8588-4ffc-90aa-be7f9d34e9d3.png",
"voice": "Melissa",
"prompt": "Hey friends! Welcome to the GPU force podcast and today we are going to discuss about the rising GPU cost!",
"resolution": "720p",
"aspect_ratio": "16:9",
"talking_style": "stable"
}'
# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
-H "Authorization: Bearer YOUR_API_KEY"API README
HeyGen Avatar 4 Image to Video
heygen/heygen-avatar4/image-to-video animates a supplied portrait into a lifelike presenter performance with speech-aligned facial movement and expressive behavior. Avatar 4 can turn a single image into a speaking avatar while preserving facial identity and adding natural expression beyond simple mouth movement. This combination makes the model a practical choice when the creative outcome depends on those qualities rather than on a generic media conversion.
For production work with heygen/heygen-avatar4/image-to-video, the workflow suits explainers, training, localization, personalized outreach, and presenter-led content where a reusable human presence needs to deliver changing material. The result is most reliable when the source material and creative brief clearly describe the intended subject, progression, visual or sonic character, and the qualities that must remain unchanged.
Highlights
Speech-driven facial animation aligns mouth shapes, expression, and timing with the performance.
Portrait animation turns one still image into a recognizable, expressive presenter.
Presenter consistency supports repeated videos without reshooting the same person.
Expressive performance turns scripted material into an engaging on-camera delivery.
Pricing
| Generated or processed duration | Price |
|---|---|
| Per second | $0.100 |
When to Use
| ✅ Good fit | ❌ Consider alternatives |
|---|---|
| A still image should anchor the video's subject and composition | The whole scene should be invented from text alone |
| A managed asynchronous result is suitable for the production pipeline | A synchronous, interactive editor is essential |
| The documented controls cover the required duration, framing, or format | The project needs controls outside this endpoint's schema |
| Creative iteration benefits from a repeatable request structure | Exact deterministic pixels, frames, geometry, or samples are mandatory |
| A finished downloadable media asset is the desired deliverable | Editable source layers or a native project file are required |
Prompt Guide
For audio transformation, state the intended result first, then add the subject or source treatment, progression, style, and delivery constraints. Keep one creative variable per phrase, use the documented field names for controls, and change one setting at a time when comparing results.
{
"aspect_ratio": "16:9",
"audio": "https://example.com/source.wav",
"image": "https://v3b.fal.media/files/b/0a90062c/A7EIviZqNxZ2HAs0yHeZ6_77a05b99-8588-4ffc-90aa-be7f9d34e9d3.png",
"prompt": "Hey friends! Welcome to the GPU force podcast and today we are going to discuss about the rising GPU cost!",
"resolution": "720p"
}
Technical Specs
| Spec | Value |
|---|---|
| Model ID | heygen/heygen-avatar4/image-to-video |
| Inputs | aspect_ratio, audio, image, prompt, resolution, talking_style, voice |
| Required inputs | image |
| Output fields | content_type, url |
| Execution | Async (submit, then poll for result) |
| Resolution | 360p / 480p / 540p / 720p / 1080p |
| Aspect Ratio | 16:9 / 9:16 / 4:5 / 5:4 / 1:1 / auto |