heygen-video-1 through Vercel for text-to-video, first-frame and reference-based generation. Existing HeyGen clients can use the official create and status formats. If you already use the AIsa video API, keep using POST /v1/video/generations. Both routes share task IDs and each task is billed once.
Use the official HeyGen API format
If your client already calls HeyGen’s/v3/models/videos, keep the same paths and request body for the parameters listed below. Replace the URL prefix and supply your AIsa API key in the existing x-api-key header.
Compatibility covers creation and status for this model. Last-frame conditioning, asset uploads and callback delivery are currently unsupported. Omit
Idempotency-Key when creating a task. Both routes reject this replay header with HTTP 400 before charging.
Create a video
This example generates a five-second video at 480p. A successful submission returns HTTP 202. Save thedata.video_id from the response.
Retrieve the result
SetVIDEO_ID to the returned data.video_id. Poll until data.status is completed, failed, or cancelled. Download a completed video from data.video_url before the signed link expires. A failed task includes failure_message.
Use the AIsa video generation API
If your client already usesPOST /v1/video/generations, keep the same endpoint and Bearer authentication and set model to heygen-video-1. The create response returns the task ID in id. Use it as VIDEO_ID below. Once the task completes, read result.video_url. You can also poll that same ID through the HeyGen route without creating another task.
Supported parameters
Duration defaults to 5 seconds. Reference mode requires 5–15 seconds, at least one image or video, and at most 12 assets total (up to 9 images, 3 videos and 3 audio clips). With reference video input the quote is an upper bound. For text and first-frame generation withquality or turbo, use 5–30 whole seconds. With ultraquality or disabled, use 5–15. Set duration to "auto" to estimate the length from quoted dialogue. Resolution defaults to 768p; supported values are 480p, 768p, 1080p and 2k when priced for your model. At 1080p and 2k, select 16:9 or 9:16. Lower resolutions also support 21:9, 4:3, 1:1, and 3:4. An optional integer seed ranges from 0 to 4294967295.
For image_to_video, pass the first frame in image. For reference_to_video, pass images in reference_images. Use an HTTPS URL or inline Base64. For example, a first-frame input looks like {"type":"url","url":"https://example.com/first.png"}. The output follows the first frame’s aspect ratio.
What if creation times out?
Once you have a task ID, poll it for the result. A503 video_submission_pending response can also include an ID you can poll. If the connection drops before you receive an ID, avoid automatically retrying the create request: each accepted submission starts a separately billed task.
For a completed task, both endpoints reuse a refreshed result URL for up to one minute per API instance. During a temporary Gateway outage, the API returns the last available URL.
Billing
The generation mode selects the per-second rate. Inreference_to_video, image-only references use the reference-mode rate for the output seconds. For example, at a customer rate of $0.035 per second, a 5-second output costs $0.175. The additional 15-second reservation and invoice-based calculation below apply only when the request includes a reference video.
Pass up to three videos in reference_videos, each as an HTTPS URL or inline Base64. Each video may be up to 16 MiB. Use a stable HTTPS URL for large files: the Vercel asynchronous job envelope has a 300 KB limit on inline requests. The URL must serve the same file until the task completes. For any number of reference videos, AIsa reserves the requested output duration plus 15 seconds total at your customer rate. AIsa does not download the references. After generation, AIsa divides the verified Gateway charge by the upstream per-second rate saved at submission, then applies your saved customer rate to those billable seconds. For example, a 5-second request reserves 20 seconds; if the upstream charge corresponds to 7 seconds, you pay for 7 and the other 13 are released. If the charge is unavailable or inconsistent, settlement remains pending and is retried. For video references, input_video_duration is omitted while pending and derived from the billable seconds after settlement.