> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voidai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Video

> Get the status and details of a video generation task

```
GET /v1/videos/{id}
```

Retrieves the current status and details of a specific video generation task.

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the video.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the video.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the video generation:

  * `pending` - Queued for processing
  * `processing` - Currently being generated
  * `completed` - Ready for download
  * `failed` - Generation failed
</ResponseField>

<ResponseField name="prompt" type="string">
  The original prompt used for generation.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for generation.
</ResponseField>

<ResponseField name="size" type="string">
  The dimensions of the video.
</ResponseField>

<ResponseField name="duration" type="number">
  The duration of the video in seconds (available when completed).
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp of when the task was created.
</ResponseField>

<ResponseField name="completed_at" type="integer">
  Unix timestamp of when the task completed (if applicable).
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the generation failed.
</ResponseField>

## Examples

### Check Video Status

<CodeGroup>
  ```python Python theme={null}
  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']}")
  ```

  ```typescript TypeScript theme={null}
  const videoId = 'vid_abc123';

  const response = await fetch(`https://api.voidai.app/v1/videos/${videoId}`, {
    headers: {
      'Authorization': 'Bearer sk-voidai-your_key_here'
    }
  });

  const video = await response.json();
  console.log(`Status: ${video.status}`);

  if (video.status === 'completed') {
    console.log(`Duration: ${video.duration}s`);
    console.log('Ready for download!');
  } else if (video.status === 'failed') {
    console.log(`Error: ${video.error}`);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/videos/vid_abc123 \
    -H "Authorization: Bearer sk-voidai-your_key_here"
  ```
</CodeGroup>

### Poll Until Complete

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```typescript TypeScript theme={null}
  async function waitForVideo(videoId: string, timeout = 600000, interval = 10000) {
    const startTime = Date.now();

    while (Date.now() - startTime < timeout) {
      const response = await fetch(`https://api.voidai.app/v1/videos/${videoId}`, {
        headers: { 'Authorization': 'Bearer sk-voidai-your_key_here' }
      });
      const video = await response.json();

      if (video.status === 'completed') {
        return video;
      } else if (video.status === 'failed') {
        throw new Error(`Video generation failed: ${video.error}`);
      }

      console.log(`Status: ${video.status}... waiting ${interval/1000}s`);
      await new Promise(resolve => setTimeout(resolve, interval));
    }

    throw new Error('Video generation timed out');
  }

  const video = await waitForVideo('vid_abc123');
  console.log(`Video ready! Duration: ${video.duration}s`);
  ```
</CodeGroup>

## Response Examples

### Pending Video

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

### Completed Video

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
}
```