# Get Video Status/Details
Retrieves the status and details of a specific video by ID.
**Note:**
* The `thumbnail_url`, `video_url` and `video_url_caption` fields return time-limited links that expire after 7 days. The video itself does not expire, only the links do. To ensure continuous access, you have two options:
1. **Download the Video:** Save the video locally within the 7-day window.
2. **Regenerate the URL:** Call the endpoint again whenever you need to access the video file. Each time you call the video status endpoint, the `Expires` and related query parameters in the URL are regenerated, reflecting the new expiration time.
* Scroll down to the **Responses** section below and expand the status code(s) to view the detailed response schema.
* Refer to the **RESPONSE** panel on the right and choose an example to explore different video processing statuses (such as waiting, pending, processing, completed, or failed) and see how each status appears in the API response examples.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "heygen-api",
"version": "4.0.8"
},
"servers": [
{
"url": "https://api.heygen.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/v1/video_status.get": {
"get": {
"summary": "Retrieve Video Status/Details",
"description": "This endpoint allows you to retrieve the status and details of a specific video.",
"operationId": "video-status",
"parameters": [
{
"name": "video_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Unique identifier of the video to retrieve status and details. Can be retrieved from Create Avatar Video (V2) or Create a WebM Video endpoint.",
"required": true
}
],
"responses": {
"200": {
"description": "Status retrieved successfully - Expand to view the detailed response schema.",
"content": {
"application/json": {
"examples": {
"Completed": {
"value": "// If the video rendering is completed, the response looks like this: \n\n{\n \"code\": 100,\n \"data\": {\n \"callback_id\": \"ava124\",\n \"caption_url\": \"https://resource2.heygen.ai/movio/video/kjnny36d9d0b45c07651da6840a1c739/caption.ass\",\n \"created_at\": 1759307076,\n \"duration\": 6.42612,\n \"error\": null,\n \"gif_url\": \"https://resource2.heygen.ai/video/nbyyq36d9d0b45c08135da1287a1c739/gif.gif\",\n \"id\": \"fcbba36d9d0b45c08135da6840a1c739\",\n \"status\": \"completed\",\n \"thumbnail_url\": \"https://files2.heygen.ai/aws_pacific/avatar_tmp/05ebafd83a8541j7n8d56a14c8a4ce72/fcbba36d9d0b45c08135da1234a1c739.jpeg?Expires=1759918068&Signature=Rj6-QTD5FeIjR7FmLbfeqFaRP2CrrEL~CfJ5EZFH0rCsi70KPQKH5X0Q-uuz5ecAEvItFLh1BupZms3-NUYIrPsiT2Cak0bPFpB9VDrnA3ojXe6r4Bmj6BsWI3Z0rNABqjpWs2Kg57Zg~1ndz5rntpwfcHvdAPnawYGlxt1FJzT~tQcXylK9Tc6ukAIce9hdqX7b1fAPVfbb-gg8T08f-hhMXz77Rw~-wG27EU9lgUZszhXRtKn6xGMqobz-cwC4b8cmpnghPl8pnQh1ldfbS6RTqsbuPD6JqGtxgpoLmh3FOYR7MDsqVbaViED2cmbpdSz5r3ofhRH4O4VJixh9Rg__&Key-Pair-Id=K38HBHY5LX3X2H\",\n \"video_url\": \"https://files2.heygen.ai/aws_pacific/avatar_tmp/05rutfd83a8541f0b8d23a14c8a4ce72/fcbba36d9d0b45c08135da6840a1c739.mp4?Expires=1752218068&Signature=NIAHPL6Zd7no6pRL37Q50byoyik5Ooo64FBFX1bj-PL4fZu48kJVtsmdaewBYlPe5yvek8O7dkgbkA-5gRBqF30e1tlbN95qNB~verG8Eca23P2rtnjvgGYlKh0GeN-bcKhKt9LP~jgRmoux9fJ~GL0raIK1QmtgyKTiDUSJRWR2fIADKEGvEdMHYGRUx114Vl~mE5DyWcABOf6b9Le59Wn0vdg1XHeDBz4GdWZ8gsrFrQ8yzM4dCZnsqN5PnOZVuJ4BI9OWKxCC5CsJJTdSVtGIYa0xVeB6pUbnoW9TPXpLvN2XOTmcPmoGg51bKS78BbY-nbdudkQbbiGl0NsClQ__&Key-Pair-Id=K38KBHX5LX3X2H\",\n \"video_url_caption\": \"https://files2.heygen.ai/movio/video/tolla36d9d0b45c08135da6840a1c739/134e39ab3fc94cab92785f2b211f26e2/caption.mp4?Expires=1759918068&Signature=F2ho-WgCPs5Af0F51TtbamBXg9PNlfz7Fcy9hSPZBYJfSc4WG8DInAfJex1FJRY7RYl7fMgwWcm6KxIvWLqS44khvAn8gc~Q2Rd6fSzkY27oj-6yFlNOL33QO-0i9L8a42Aehcluw~uIqDZSNvtOPj5cN0EQArx~LL-qZhWT1Ty~LBBkBXa~6qhL3GaUS1mw9VKyc4ESf1LR16rCqS7FTBg1sGTEfOcNs09vaLzd1aFFzO1MpFV5fV503oUWg~U-czl0MilcLDVr2GcsPWWyHIcTB4ULkZDFxYSz5mFEa-CDDDOgTGisesQqE61SXR~1e51QBdAO~-1OyO~tUAr9zQ__&Key-Pair-Id=K37HBHX5LX3X2H\"\n },\n \"message\": \"Success\"\n}",
"summary": "Completed"
},
"Processing": {
"summary": "Processing",
"value": "// If the video is processing, the response will look like this:\n\n{\n \"code\": 100,\n \"data\": {\n \"callback_id\": null,\n \"caption_url\": null,\n \"duration\": null,\n \"error\": null,\n \"gif_url\": null,\n \"id\": \"fcbba36d9d0b45c08135da6840a1c739\",\n \"status\": \"processing\",\n \"thumbnail_url\": null,\n \"video_url\": null,\n \"video_url_caption\": null\n },\n \"message\": \"Success\"\n}\n"
},
"Waiting": {
"summary": "Waiting",
"value": "// If the video is in waiting state, the response will look like this:\n\n{\n \"code\": 100,\n \"data\": {\n \"callback_id\": null,\n \"caption_url\": null,\n \"duration\": null,\n \"error\": null,\n \"gif_url\": null,\n \"id\": \"fcbba36d9d0b45c08135da6840a1c739\",\n \"status\": \"waiting\",\n \"thumbnail_url\": null,\n \"video_url\": null,\n \"video_url_caption\": null\n },\n \"message\": \"Success\"\n}\n"
},
"Pending": {
"summary": "Pending",
"value": "// If the video is in the queue, you will get a response like this:\n{\n \"code\": 100,\n \"data\": {\n \"callback_id\": null,\n \"caption_url\": null,\n \"duration\": null,\n \"error\": null,\n \"gif_url\": null,\n \"id\": \"fcbba36d9d0b45c08135da6840a1c739\",\n \"status\": \"pending\",\n \"thumbnail_url\": null,\n \"video_url\": null,\n \"video_url_caption\": null\n },\n \"message\": \"Success\"\n}\n"
},
"Failed": {
"summary": "Failed",
"value": "/*\nIf an error occurs during the rendering process, the status is set to `\"failed\"`, \nand detailed information is returned in the `error` field.\n*/\n{\n \"code\": 100,\n \"data\": {\n \"callback_id\": null,\n \"caption_url\": null,\n \"duration\": null,\n \"error\": {\n \"code\": 40119,\n \"detail\": \"Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos\",\n \"message\": \"Video is too long\"\n },\n \"gif_url\": null,\n \"id\": \"2dbba36d9i0b45c08135d26840a1c739\",\n \"status\": \"failed\",\n \"thumbnail_url\": null,\n \"video_url\": null,\n \"video_url_caption\": null\n },\n \"message\": \"Success\"\n}\n"
}
},
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Status code indicating the result of the API request. A 100 indicates a successful response. Other codes might indicate different types of errors. Refer to the Error Responses for more details."
},
"data": {
"type": "object",
"properties": {
"callback_id": {
"type": "string",
"description": "Custom ID for callback. Returned in the webhook for tracking purposes. "
},
"caption_url": {
"type": "string",
"description": "URL of the captions file in .ass format, if generated. Returned only if 'caption: true' is specified when generating videos. "
},
"created_at": {
"type": "number",
"description": "Unix timestamp when the video was created."
},
"duration": {
"type": "number",
"description": "Duration of the video in seconds.",
"format": "float"
},
"error": {
"type": "string",
"description": "Displays error message when the request fails; null if the request is successful."
},
"gif_url": {
"type": "string",
"description": "URL of the generated GIF preview."
},
"id": {
"type": "string",
"description": "Unique identifier of the video."
},
"status": {
"type": "string",
"description": "Current status of the video. ",
"enum": [
"pending: Waiting in queue",
"failed: Rendering failed",
"completed: Video rendered successfully",
"processing: Video is rendering"
]
},
"thumbnail_url": {
"type": "string",
"description": "URL of the video's thumbnail image. This URL will expire in 7 days. Call the endpoint again to generate a new one after expiration."
},
"video_url": {
"type": "string",
"description": "URL of the rendered video. This URL will expire in 7 days. Call the endpoint again to generate a new one after expiration."
},
"video_url_caption": {
"type": "string",
"description": "URL of the rendered caption video, if 'caption: true' was specified. This URL will expire in 7 days. Call the endpoint again to generate a new one after expiration."
}
},
"description": "Contains the video details. "
},
"message": {
"type": "string",
"description": "New field for messages. Contains human-readable messages explaining the status of the request. In case of errors, it returns an explanation."
}
}
}
}
}
},
"400": {
"description": "Request exceeds the request limit or the request body is corrupted.",
"content": {}
},
"404": {
"description": "Video doesn't exist or you don't have access to the page.",
"content": {}
},
"424": {
"description": "Invalid parameters entered.",
"content": {}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```