Introduction
Send image_url with a prompt describing the movement you want to add. Our photo tests kept the source person and composition at 480p, 1080p, and 2k; choose the native tier around your delivery dimensions.
| Field | Value |
|---|---|
| Input | Image |
| Output | Video |
| Publisher and model | HeyGen — HeyGen Video 1.0; API name heygen-video-1 |
| Public endpoint names | heygen/video-1/text-to-video; heygen/video-1/image-to-video; heygen/video-1/reference-to-video |
| Requested duration | 5–15 seconds across the three endpoints |
| Text generation tiers | 480p or 768p; output includes AAC stereo audio |
| Photo animation tiers | 480p, 768p, 1080p, 2k — native resolution tiers |
| Measured image output sizes | 832×480 at 480p; 1890×1080 at 1080p; 2688×1536 at 2k |
| Reference output settings | 480p or 768p; aspect ratio 16:9 or 9:16 |
| Reference input budget | Up to 12 items combined; reference videos total up to 15 seconds |
| Prompt rewrite modes | disabled, turbo, quality |
| Measured file duration | Five-second requests returned 5.18–5.26 seconds; billed as five requested seconds |
| Billing unit | Requested output seconds; reference-video seconds also count, and each image from the third adds a per-image charge |
Key features & highlights
A written scene becomes a clip
Text-to-video creates a 5–15 second scene at 480p or 768p and includes an audio track. Our 480p, five-second run returned 832×480 at 24 fps with AAC stereo audio in about 10 seconds of processing. That observation describes one run, rather than a turnaround promise.
Keep the source person in view
Image-to-video uses image_url and a movement prompt to animate a supplied photo. Our 480p, 1080p, and 2k tests kept the source person and composition, with the 2k run delivering 2688×1536 pixels. Choose this input pattern when continuity with a particular photograph matters.
Cast the person and the object separately
Reference-to-video can combine images, videos, and audio clips within a 12-item total. The two-image portrait-and-bottle test produced a vertical shot with the man holding the supplied bottle. A separate mixed-reference run followed its video closely and lost the photo’s face, so assign a clear purpose to each input.
Change a prompt without losing the setup
The seed and prompt_optimization_mode controls help organize revisions. Keep a seed fixed while comparing one change; it does not guarantee an identical result. Select disabled to avoid a prompt rewrite, or try turbo or quality when you want the model to rewrite the brief.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Specify the change you want to see, such as a head turn or a glance, and name what should remain recognizable. at least 1 characters · at most 32000 characters |
image_url | Yes | Supply the source photo for the person and composition you want to animate. Check that its framing already suits the intended shot before describing the movement. |
resolution | No | Select 480p, 768p, 1080p, or lowercase 2k. Our tested outputs measured 832×480, 1890×1080, and 2688×1536 at 480p, 1080p, and 2k respectively. |
duration_seconds | No | Set a requested duration between 5 and 15 seconds. The billing unit follows that request even if whole-frame rounding makes the file slightly longer. |
prompt_optimization_mode | No | Use disabled to keep the brief from being rewritten, or turbo or quality to allow a rewrite. Compare the motion with one mode held constant before changing the tier. |
seed | No | A fixed seed helps assess one motion-prompt change at a time. It is a comparison aid rather than a guarantee that the returned clip will be identical. |
Pricing
Charged per requested output second at the displayed rate for the selected native resolution tier; extra frame-rounded playback time does not add output seconds to the bill.
| Specification | Price |
|---|---|
| $0.03 / second |
| $0.054 / second |
| $0.144 / second |
| $0.144 / second |
Use cases
A scene before the shoot
Send a text brief for a potter in their thirties, wearing a canvas apron in a sunlit studio, turning toward a shelf. A five-second request at 480p gives you a concept clip with an audio track to review before a shoot.
A portrait with a small gesture
Provide a licensed portrait of a woman in her thirties in an evening dress beside a window, then ask for a head turn and a slow camera move. Image-to-video returns a short animation guided by that photo; inspect the person and composition against the source.
A presenter with a supplied product
Attach a man’s portrait as <Picture 1> and a dropper-bottle photo as <Picture 2>, then request a 9:16 shot of him holding the bottle. Our two-image test used both references and took about 158 seconds to process.
A motion-led concept
Supply a portrait, a four-second motion clip, and an audio reference with roles named in the prompt. Our mixed-input run followed the video’s motion and scene closely, but did not retain the portrait’s face; use this pattern when motion matters more than that face.
A larger photo-based deliverable
Pair a source photo with a restrained movement prompt and select 1080p or 2k for image-to-video. Our five-second tests returned native 1890×1080 and 2688×1536 outputs while keeping the source person.
Prompt guide & pro tips
Match the endpoint to the input
Choose text-to-video for a written scene, image-to-video for a photo, or reference-to-video for multiple source items. Photo animation offers 1080p and 2k when you need those tiers.
Prepare a focused scene brief
Describe the person, wardrobe, setting, lighting, and one visible action. For references, tie the action to tokens such as <Picture 1> and <Picture 2>, and use text, voices, and likenesses you have rights to use.
Submit the generation task
POST to https://api.spicyapi.ai/api/v1/jobs/createTask with Bearer authentication and JSON such as {"model":"heygen/video-1/text-to-video","input":{"prompt":"A potter in their thirties turns toward a shelf.","
duration_seconds":5,"resolution":"480p"}}.Retrieve and review the clip
Save data.taskId and query GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID to check the result. Review the returned video, then hold the seed fixed while testing one revision; repeated settings do not promise an identical result.
HeyGen Video 1.0 API for image to video
HeyGen Video 1.0 animates a supplied photo for 5–15 seconds, with native 480p, 768p, 1080p, and 2k tiers. Our image tests retained the source person and composition, so this endpoint is a practical starting point when the photograph already defines the shot.
Send the photo and its movement
Submit heygen/video-1/image-to-video to https://api.spicyapi.ai/api/v1/jobs/createTask with the JSON below. Set Authorization: Bearer YOUR_SPICY_API_KEY and Content-Type: application/json, and replace the photo URL with your own image.
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}
The sample illustrates a proposed portrait animation, rather than an additional test result. Use a photograph and likeness you have the right to use.
Collect the returned video
The submission returns a task ID that you use to retrieve the result with GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID. These shortened response examples show the relevant fields with illustrative values, not a new run.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}
The SpicyAPI task documentation describes the full envelope. Save the returned asset and compare the moving person and framing against the input photograph.
Set the animation parameters
Pass image_url alongside the prompt, then choose duration and a native resolution tier. The settings below intentionally separate the photo input from the movement you want the model to add.
| Parameter | What to supply |
|---|---|
image_url | The source photo that defines the person and composition. |
prompt | The action, camera behavior, lighting, and scene direction. |
duration_seconds | A requested output duration from 5 to 15 seconds. |
resolution | 480p, 768p, 1080p, or 2k; use lowercase 2k in JSON. |
prompt_optimization_mode | disabled avoids a rewrite; turbo and quality allow one. |
seed | A comparison control for revisions, without an identical-result promise. |
Preserve what the photograph establishes
Describe a small change from the source pose rather than rebuilding the whole scene in words. A head turn or a glance gives you a clear action to judge while comparing the person and framing against the still.
HeyGen says that image-to-video opens on the supplied picture. Its prompting guidance recommends restrained camera movement and explicit contact points for gestures. Those are publisher descriptions; our evidence here is the photo continuity and native dimensions recorded in the supplied tests.
- Select a photo with the person and setting you want to retain.
- Write one motion instruction and state which visual elements matter.
- Review a 480p trial for the person's appearance and the action.
- Try 1080p or 2k after the scene direction is useful, holding the seed fixed for comparison.
Compare our measured sizes
Our five-second photo tests produced native outputs at the requested tiers and kept the source person. These measurements describe the tested source composition, rather than a universal pixel map for every photograph.
| Requested tier | Measured output |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
768p is also supported, but we have no image-test dimensions for that tier to report. We have no image-specific processing-time measurement either, so the text run's roughly 10 seconds should not be treated as this endpoint's timing estimate.
Plan billing and review duration
Image animation bills the requested output seconds at the rate displayed for your selected tier on this page. Five-second files across our tests lasted 5.18–5.26 seconds because of whole-frame rounding, while the billed output duration remained five seconds. Extra pixels address delivery dimensions; review the movement separately before committing to another render.
Check input problems and alternatives
Check image_url, the prompt, and the resolution spelling when a request is rejected. Keep duration within 5–15 seconds and use 2k for that tier; consult the current schema and any returned task error before changing fields. A result that changes an important gesture needs visual review even when the task succeeded.
Choose text-to-video when you want a scene from words without a source photo. Choose reference-to-video to assign a portrait and product separate roles, while remembering that its video inputs can dominate identity. For a photo intended to speak as an avatar, review HeyGen Avatar IV instead.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/image-to-video",
"input": {
"duration_seconds": 5,
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.

