HeyGen Video

POST/v1/media/queue

from $0.04/second

Overview

HeyGen Video — general-purpose video generation up to 2K with first-frame image-to-video. Async operation — submit a job, poll for completion.

Property	Value
Model ID	`heygen/heygen-video-1`
Provider	HeyGen
Resolutions	480p, 768p, 2K
Aspect Ratios	21:9, 16:9, 4:3, 1:1, 3:4, 9:16
Duration	5–15 seconds
Audio Generation	Not supported
Billing	Dynamic (actual cost per job)
Pricing	from $0.04/second

Usage

All media models use the async job queue. Submit a job, then poll for the result.

Step 1: Submit Job

Text-to-Video

const res = await fetch('https://api.yepapi.com/v1/media/queue', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'heygen/heygen-video-1',
    prompt: 'A cinematic drone shot over a rugged coastline at golden hour',
    options: {
      aspectRatio: '16:9',
      resolution: '480p',
      duration: '5',
    },
  }),
});
const { data } = await res.json();
// data.jobId — use this to poll for results

curl -X POST https://api.yepapi.com/v1/media/queue \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "heygen/heygen-video-1", "prompt": "A cinematic drone shot over a rugged coastline", "options": {"aspectRatio": "16:9", "resolution": "480p", "duration": "5"}}'

Image-to-Video

Pass a reference image via imageData to generate a video that starts from a still image (imageRole: 'first_frame').

Jobs that include a reference image are billed at the reference-image rates in Pricing.

const res = await fetch('https://api.yepapi.com/v1/media/queue', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'heygen/heygen-video-1',
    prompt: 'Animate this scene — clouds drifting, light changing',
    options: {
      aspectRatio: '16:9',
      resolution: '480p',
      duration: '5',
      imageRole: 'first_frame',
    },
    imageData: {
      mimeType: 'image/jpeg',
      base64: '...', // Base64-encoded image
    },
  }),
});

Step 2: Poll for Result

const status = await fetch(`https://api.yepapi.com/v1/media/status/${data.jobId}`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' },
});
const { data: job } = await status.json();
// job.status — "pending" | "processing" | "completed" | "failed"
// job.result.video — { mimeType, base64 } when completed

curl https://api.yepapi.com/v1/media/status/JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

Request Body

Parameter	Type	Required	Description	Default
`model`	`string`	Yes	`heygen/heygen-video-1` or alias `heygen-video`	—
`prompt`	`string`	Yes	Text description of the video to generate	—
`options.aspectRatio`	`string`	No	One of: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16	`16:9`
`options.resolution`	`string`	No	`480p`, `768p`, `2K`	`480p`
`options.duration`	`string`	No	`5` to `15` (seconds)	`5`
`options.imageRole`	`string`	No	How to use the input image: `first_frame`	`first_frame`
`imageData.mimeType`	`string`	No	MIME type of input image (image/png, image/jpeg, image/webp)	—
`imageData.base64`	`string`	No	Base64-encoded input image for image-to-video generation	—

Pricing

Tier	Cost/sec
480p	$0.04
768p	$0.08
2K	$0.21
480p with reference image	$0.15
768p with reference image	$0.21
2K with reference image	$0.38

Example: 5-second 480p video ≈ 5 x $0.04 = $0.20. Billing is dynamic — each job is billed from the actual cost of the finished video, so shorter or lower-resolution jobs cost less.

Info

Video jobs can take several minutes to complete. Results retained for 1 hour.

Under the Hood

HeyGen Video

On this page