Skip to main content
GET /v1/videos/{id}
Retrieves the current status and details of a specific video generation task.

​
Path Parameters

​
id
string
required
The unique identifier of the video.

​
Response

​
id
string
Unique identifier for the video.
​
status
string
Current status of the video generation:
  • pending - Queued for processing
  • processing - Currently being generated
  • completed - Ready for download
  • failed - Generation failed
​
prompt
string
The original prompt used for generation.
​
model
string
The model used for generation.
​
size
string
The dimensions of the video.
​
duration
number
The duration of the video in seconds (available when completed).
​
created_at
integer
Unix timestamp of when the task was created.
​
completed_at
integer
Unix timestamp of when the task completed (if applicable).
​
error
string
Error message if the generation failed.

​
Examples

​
Check Video Status

import requests

video_id = "vid_abc123"

response = requests.get(
    f"https://api.voidai.app/v1/videos/{video_id}",
    headers={"Authorization": "Bearer sk-voidai-your_key_here"}
)

video = response.json()
print(f"Status: {video['status']}")

if video['status'] == 'completed':
    print(f"Duration: {video['duration']}s")
    print("Ready for download!")
elif video['status'] == 'failed':
    print(f"Error: {video['error']}")

​
Poll Until Complete

import time
import requests

def wait_for_video(video_id, timeout=600, interval=10):
    """Wait for video to complete, with timeout."""
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(
            f"https://api.voidai.app/v1/videos/{video_id}",
            headers={"Authorization": "Bearer sk-voidai-your_key_here"}
        )
        video = response.json()

        if video['status'] == 'completed':
            return video
        elif video['status'] == 'failed':
            raise Exception(f"Video generation failed: {video.get('error')}")

        print(f"Status: {video['status']}... waiting {interval}s")
        time.sleep(interval)

    raise TimeoutError("Video generation timed out")

video = wait_for_video("vid_abc123")
print(f"Video ready! Duration: {video['duration']}s")

​
Response Examples

​
Pending Video

{
  "id": "vid_abc123",
  "status": "pending",
  "prompt": "A serene beach at sunset with gentle waves",
  "model": "sora-2",
  "size": "1920x1080",
  "created_at": 1701691200
}

​
Completed Video

{
  "id": "vid_abc123",
  "status": "completed",
  "prompt": "A serene beach at sunset with gentle waves",
  "model": "sora-2",
  "size": "1920x1080",
  "duration": 10.0,
  "created_at": 1701691200,
  "completed_at": 1701691500
}

​
Failed Video

{
  "id": "vid_abc123",
  "status": "failed",
  "prompt": "A serene beach at sunset with gentle waves",
  "model": "sora-2",
  "size": "1920x1080",
  "created_at": 1701691200,
  "error": "Content policy violation detected"
}