---
title: "Get HeyGen Video"
method: GET
path: "/v3/models/videos/{video_id}"
tags: ["Models"]
---

# Get HeyGen Video

`GET /v3/models/videos/{video_id}`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/models/videos/{video_id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Returns a HeyGen Video generation: `pending`, `processing`, `completed`, `failed` or `cancelled`. Completed results include a fresh `video_url`, duration and dimensions; failed results include `failure_code` and `failure_message`. Poll again to refresh an expired URL.

## Path parameters

- `video_id` string, required

## Response `200`

Successful response

- object
  - `data` ModelVideoResponse
    - `video_id` string, required: Generated video identifier.
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled', required: Current generation status.
    - `model` 'heygen-video-1', required
    - `created_at` integer, required: Request creation time as Unix seconds.
    - `video_url` string, nullable: Download URL, present when completed. Poll again to obtain a fresh URL.
    - `duration` integer, nullable: Generated video duration in seconds, present when completed.
    - `input_video_duration` number, nullable: Total reference-video duration allocated for billing, in seconds, with a shared 15-second budget.
    - `aspect_ratio` string, nullable: Output aspect ratio. Adaptive outputs report the actual width:height ratio after pixel alignment.
    - `width` integer, nullable: Actual output width in pixels, present when reported by the renderer.
    - `height` integer, nullable: Actual output height in pixels, present when reported by the renderer.
    - `seed` integer, nullable: Generation seed, present when completed.
    - `timings` ModelVideoTimings
      - `inference` number, required: Diffusion transformer execution time in seconds. Excludes other inference stages, encoding, and queueing.
    - `failure_code` 'generation_failed' | 'generation_cancelled' | 'usage_limit_reached', nullable: Failure code, present when failed or cancelled. `usage_limit_reached` means the charge was refused because a usage limit a workspace admin set (the API key's credit limit or the member's usage limit) was reached; `failure_message` is the limit's own message.
    - `failure_message` string, nullable: Failure explanation, present when failed or cancelled.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/models/videos/:video_id/get.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)