get https://api.heygen.com/v1/video_status.get
This endpoint allows you to retrieve the status and details of a specific video.
Response
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the object. |
| error | json | Optional, the error detail of the video. |
| status | string | Video status, one of - processing (The video is rendering)- completed (The video render success)- failed (An error occurred when rendering video).- pending (The video rendering waiting in queue). |
| video_url | string | The URL of the video after completed. The URL will expire in 7 days. |
| video_url_caption | string | The URL of the caption video after completed when you create video with open_caption. The URL will be expired in a few days. |
| callback_id | string | A custom data that you wish HeyGen returns to you via webhook or video_status.get. Set when calling video.generate and template.generate |
| duration | float | length of the video |
| thumbnail_url | string | The URL of the video thumbnail after completed. |
| created_at | numbers | Creation time (Unix timestamp) |
// If your video is processing, you'll get a response like this:
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": null,
"gif_url": null,
"id": "<id>",
"status": "processing",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
// If your video is in the queue, you will get a response like this:
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": null,
"gif_url": null,
"id": "<id>",
"status": "pending",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
// If an error occurred in the rendering process, the status would
// change to "failed", and errors details may include in the "error" field:
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": {
"code": 40119,
"detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos",
"message": "Video is too long"
},
"gif_url": null,
"id": "<id>",
"status": "failed",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
// After the video rendering is finished, you'll get a response like this:
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": "<caption_url>",
"duration": 1.234,
"error": null,
"gif_url": "<gif_url>",
"id": "<id>",
"status": "completed",
"thumbnail_url": "<thumbnail_url>",
"video_url": "<video_url>",
"video_url_caption": null
},
"message": "Success"
}
The video file URL you get will expire in 7 days. 📆
You can observe this expiration in the URL parameters. Every time you call the video status endpoint, the
Expiresand other queries are regenerated accordingly.
Errors
- Returns a 404 HTTP response if the video doesn't exist, or if doesn't have access to the page.
- Returns a 400 HTTP response if the request exceeds the request limits or your request body is corrupted.
- Returns a 424 HTTP response if parameters are invalid.