# OpenRouter APIs — HeyGen: HeyGen Video (heygen/heygen-video-1)

Guide for calling every confirmed OpenRouter API that serves `heygen/heygen-video-1`.

Model page: https://openrouter.ai/heygen/heygen-video-1
Create an API key: https://openrouter.ai/settings/keys

## Pricing

Standard-variant prices for `heygen/heygen-video-1`, per provider, in the unit each provider bills (tokens, images, seconds of video, or characters of audio). Pay-as-you-go with no markup on the provider's price.

- HeyGen: from $0.01/second (plus 4 more; see the model page for the full price list)

Full price table, including other variants and per-request charges: https://openrouter.ai/heygen/heygen-video-1
How OpenRouter prices requests: https://openrouter.ai/pricing

## EU in-region routing

`heygen/heygen-video-1` is not currently available through EU in-region routing.

Docs: https://openrouter.ai/docs/guides/features/in-region-routing

## Authentication

Send this header with every request:

- Authorization: Bearer $OPENROUTER_API_KEY

## Video API

Generate videos with `heygen/heygen-video-1` through OpenRouter's Video API.

Docs: https://openrouter.ai/docs/guides/overview/multimodal/video-generation
Model discovery API: https://openrouter.ai/api/v1/videos/models

### Endpoint

POST https://openrouter.ai/api/v1/videos

Headers:
- Content-Type: application/json

Generation is asynchronous: the submit call returns a job, which is polled until it
finishes. The finished video is downloaded from the job, not returned inline.

### Request fields (heygen/heygen-video-1)

- model: string (required) — `"heygen/heygen-video-1"`
- prompt: string (optional when frame_images is set, otherwise required) — text description of the desired video
- duration: 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 (optional) — length of the video in seconds
- resolution: "480p" | "768p" | "1080p" | "2K" (optional) — resolution tier; interchangeable with size when paired with aspect_ratio
- aspect_ratio: "21:9" | "16:9" | "4:3" | "1:1" | "3:4" | "9:16" (optional) — aspect ratio of the generated video
- frame_images: array of frame references (optional) — images to condition the named frame on, as `{ "type": "image_url", "image_url": { "url": "…" }, "frame_type": "first_frame" }` entries; frame_type is one of "first_frame", and the url is an https URL or a base64 data URL
- input_references: array of reference assets (optional) — images to guide the generation, as `{ "type": "image_url", "image_url": { "url": "…" } }` entries
- seed: integer (optional) — sample deterministically; determinism is not guaranteed for every provider
- callback_url: string (optional) — https URL notified by webhook when the job finishes, instead of polling

These are the generation parameters this model accepts between its providers; an unlisted
value is rejected, and a listed one can still be refused by whichever provider serves the
call. `provider` (routing preferences) is accepted on every request.

### Response

The submit call returns `202` with the job:

```json
{
  "id": "job-abc123",
  "generation_id": "gen-xyz789",
  "polling_url": "/api/v1/videos/job-abc123",
  "status": "pending"
}
```

Poll `GET https://openrouter.ai/api/v1/videos/{id}` with the same Authorization header while `status` is
`pending` or `in_progress`, and stop once it is `completed`, `failed`, `cancelled`, or
`expired`:

```json
{
  "id": "job-abc123",
  "status": "completed",
  "unsigned_urls": ["https://storage.example.com/video.mp4"],
  "usage": { "cost": 0.5 }
}
```

Download the bytes from `GET https://openrouter.ai/api/v1/videos/{id}/content` (`?index=N` selects a clip
when the job produced more than one). `usage.cost` is the USD charge for the call.

### Examples

#### Text to Video

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "a slow cinematic push-in on a glowing neon sign that reads \"OpenRouter\" in the window of a cozy coffee shop on a rainy night, rain streaking down the glass, reflections rippling on wet pavement",
  "duration": 5,
  "aspect_ratio": "16:9"
}'
```

#### Image to Video

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "Slow cinematic push-in toward the glowing OpenRouter sign as light rain starts to fall, puddles rippling on the sidewalk and the warm lights inside the shop gently flickering.",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "16:9",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/heygen/heygen-video-1-20260930/9b233dfa-43c4-4651-8e19-de59b1a1ef3d/input-0.jpg"
      },
      "frame_type": "first_frame"
    }
  ]
}'
```

#### Reference to Video

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "A cyclist rides up to the OpenRouter storefront from the reference images at dusk, parks the bike under the neon sign, and walks inside as the camera follows; rain-slicked street, warm interior light.",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/bytedance-seed/seedream-4.5-20251203/d8cd2dd8-a6da-4b88-8033-4d530482f983/original-0.jpg"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/black-forest-labs/flux.2-flex/c795ffed-e7c5-4f07-94d6-d0d25402efb3/original-0.jpg"
      }
    }
  ]
}'
```

#### Text to Video 2

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "a slow cinematic push-in on a glowing neon sign that reads \"OpenRouter\" in the window of a cozy coffee shop on a rainy night, rain streaking down the glass, reflections rippling on wet pavement",
  "duration": 5,
  "aspect_ratio": "16:9"
}'
```

#### Video to Video

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "Turn this scene into a snowy winter night: snow falling and settling on the sidewalk and bicycle, frost creeping across the windows, keeping the original camera move and the glowing OpenRouter sign.",
  "duration": 5,
  "input_references": [
    {
      "type": "video_url",
      "video_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/heygen/heygen-video-1-20260930/096785bd-1735-4437-bc09-b147e9fae711/input-video-0.mp4"
      }
    }
  ]
}'
```

#### Text to Video 3

```bash
curl -X POST https://openrouter.ai/api/v1/videos \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "heygen/heygen-video-1",
  "prompt": "Bring this storefront photo to life as a short ad: a slow push-in at dusk as people stroll past, with the reference voiceover as narration.",
  "duration": 5,
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/black-forest-labs/flux-3-image-20261001/bab10114-feb0-49da-bb01-e7f659474293/original-0.png"
      }
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://model-assets.openrouter.ai/model-examples/minimax/speech-2.8-hd-20260716/82758d34-58ee-40cf-96ed-853481149e6d/original-0.mp3"
      }
    }
  ]
}'
```

### Error differences

- 404 also covers an unknown video job
- 500 — the job could not be submitted

A job that fails after acceptance reports `status: "failed"` with an `error` message rather than
an HTTP error, since the submit call already succeeded.

## Errors

Failures return `{"error": {"code": <number>, "message": <string>}}` with the HTTP status:

- 400 — malformed request or an unsupported parameter
- 401 — missing or invalid API key
- 402 — insufficient credits
- 403 — spend limit reached, key disabled, or access blocked
- 404 — unknown model or no provider can serve the request
- 429 — rate limited; retry with backoff
- 502 — the operation failed upstream; failed generations are not billed

---

Canonical version of this document: https://openrouter.ai/heygen/heygen-video-1/llms.txt