Introduction
Describe the subject, setting, action, and intended sound in prompt, then select duration_seconds and a resolution. Use seed to compare revisions and prompt_optimization_mode to control whether the brief can be rewritten.
| Field | Value |
|---|---|
| Input | Text |
| 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 | Describe who appears, what moves, where the shot takes place, and what should be heard. A specific action and camera view make the returned scene easier to evaluate. at least 1 characters · at most 32000 characters |
aspect_ratio | No | Choose a frame shape from this endpoint’s current options before submitting. Plan the framing around the destination rather than relying on the scene text to select it. |
resolution | No | Choose 480p or 768p for text generation. |
duration_seconds | No | Request between 5 and 15 seconds. Five-second files in our tests lasted 5.18–5.26 seconds after frame rounding, while billing counted five output seconds. |
prompt_optimization_mode | No | Set disabled when you want to avoid a prompt rewrite. Both turbo and quality let the model rewrite your brief, so hold this choice steady when comparing prompts. |
seed | No | Keep the seed fixed and change one scene detail to make a comparison easier. Matching the seed does not guarantee an identical result. |
Pricing
Billed per requested output second at the rate shown for 480p or 768p; whole-frame rounding does not increase the requested duration billed.
| Specification | Price |
|---|---|
| $0.03 / second |
| $0.054 / 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 text to video
HeyGen Video 1.0 turns a written scene into a 5–15 second clip at 480p or 768p with an AAC stereo audio track. This endpoint needs a prompt rather than an image, making it suitable for a concept shot before you have photography or footage.
Submit a scene request
Call heygen/video-1/text-to-video by posting this JSON to https://api.spicyapi.ai/api/v1/jobs/createTask. Supply Authorization: Bearer YOUR_SPICY_API_KEY and Content-Type: application/json; the scene below is a suggested request, not a reproduction of our measured test.
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}
Retrieve the task response
Read data.taskId from the submission response, then query GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID with your Bearer key. A successful result exposes the generated asset URL; the examples here omit unrelated response fields and use placeholder IDs and URLs.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}
See the task API guide for the complete request and response contract. Opening an asset URL lets you review the picture and listen to the generated track.
Choose the scene controls
Use the following controls to specify duration, picture size, and how the prompt is handled. Select an aspect ratio from the endpoint's current options when the delivery format matters.
| Parameter | Purpose and supported settings |
|---|---|
prompt | Describe the subject, visible action, setting, light, and intended sound. |
duration_seconds | Request 5–15 seconds of output. |
resolution | Choose 480p or 768p; this endpoint has no 1080p tier. |
aspect_ratio | Select a supported frame shape in the current endpoint controls. |
prompt_optimization_mode | disabled, turbo, or quality; the latter two allow a rewrite. |
seed | Keep fixed when comparing a single prompt revision; identical output is not guaranteed. |
Direct a contained shot
Give one visible action a clear setting before adding camera instructions. For example, describe a person turning toward a shelf rather than asking for a room tour, a gesture, and a scene change in the same short clip.
HeyGen says to name the camera setup, lighting, and sound sources in the brief. Its guidance favors contained scenes and notes limitations around intricate hand movements and long on-screen copy. Treat that as publisher guidance, and review your own footage for those details.
- Name the person, clothing, place, and action in that order.
- Add a specific view, such as a static medium shot with window light.
- Describe the sounds you want; specify no music when appropriate.
- Compare a revision with the same seed and rewrite mode before changing other settings.
Read the measured result
Our neutral text test requested five seconds at 480p and returned 832×480 video at 24 fps with AAC stereo audio. Processing took about 10 seconds in that run; it does not establish a typical completion time for every scene.
Five-second requests across the supplied tests produced 5.18–5.26 second files, rounded to whole frames. If a timeline needs an exact edit point, inspect the file duration and trim it in your editor.
Understand the billing unit
Text generation is billed per second of requested output, using the current price displayed for the chosen tier on this page. A five-second request counts as five output seconds even when frame rounding makes playback slightly longer. Choose 480p for a trial of the composition, then consider 768p for the delivery you need; that is a workflow suggestion, not a measured quality ranking.
Resolve limits and choose another task
Keep the request within 5–15 seconds and select 480p or 768p before submitting. For an input error, compare the field names and resolution against the table and the current schema; for a failed task, inspect its errorCode and errorMessage rather than treating an unfinished task as a completed video.
Use image-to-video when a particular photo should guide the person and composition or when you need native 1080p or 2k. Use reference-to-video for separately supplied people, products, or motion references. A talking photo belongs in HeyGen Avatar IV; a translation task belongs in HeyGen Video Translate.
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/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "768p",
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt_optimization_mode": "disabled"
}
}'
# 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.

