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

# Retrieve Video Details

> Get detailed information about a specific video including status, duration, and download URL

## Overview

This endpoint returns detailed information about a specific video. Use it to get the current status, download URL, duration, and other metadata for a video you've created.

<Info>
  The download URL (in the `url` field) is only available when the video status is `COMPLETED`. For processing videos, check back later or use polling with this endpoint.
</Info>

### Path Parameters

<ParamField path="videoId" type="string" required>
  The ID of the video to retrieve details for
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.slidevid.ai/v1/video/vid_abc123" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const videoId = 'vid_abc123';
  const response = await fetch(`https://api.slidevid.ai/v1/video/${videoId}`, {
    headers: { 'x-api-key': 'your_api_key_here' }
  });
  const video = await response.json();
  console.log(`Video: ${video.name}`);
  console.log(`Status: ${video.status}`);
  console.log(`Duration: ${video.durationInFrames} frames (${video.durationInFrames / 25}s)`);
  if (video.url) {
    console.log(`Download: ${video.url}`);
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  videoId = 'vid_abc123'
  response = requests.get(
      f'https://api.slidevid.ai/v1/video/{videoId}',
      headers={'x-api-key': 'your_api_key_here'}
  )
  video = response.json()

  print(f"Video: {video['name']}")
  print(f"Status: {video['status']}")
  print(f"Progress: {video['progress']}%")

  if video['status'] == 'COMPLETED':
      duration_seconds = video['durationInFrames'] / 25  # 25fps
      print(f"Duration: {duration_seconds}s")
      print(f"Download URL: {video['url']}")
  elif video['status'] == 'STARTED':
      print(f"Still processing... ({video['progress']}%)")
      print(f"Message: {video['message']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "vid_abc123",
    "name": "Product Tutorial",
    "status": "COMPLETED",
    "url": "https://signed-s3-url.example.com/videos/vid_abc123.mp4",
    "durationInFrames": 6250,
    "projectId": "proj_class_001",
    "teamId": "team_xyz789",
    "thumbnail": "https://cdn.slidevid.ai/thumbnails/vid_abc123.jpg",
    "size": 15728640,
    "progress": 100,
    "message": "Video ready",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:05:00Z"
  }
  ```
</ResponseExample>

## Response Fields

<ParamField type="string">
  **id**: Unique video identifier
</ParamField>

<ParamField type="string">
  **name**: Video name/title
</ParamField>

<ParamField type="string">
  **status**: Current video status (`STARTED`, `COMPLETED`, or `FAILED`)
</ParamField>

<ParamField type="string">
  **url**: Signed URL to download the video (only available when status is `COMPLETED`)
</ParamField>

<ParamField type="integer">
  **durationInFrames**: Duration of the video in frames (at 25fps). To convert to seconds, divide by 25.
</ParamField>

<ParamField type="string">
  **projectId**: ID of the project this video belongs to
</ParamField>

<ParamField type="string">
  **teamId**: ID of the team that owns this video
</ParamField>

<ParamField type="string">
  **thumbnail**: URL to the video thumbnail image
</ParamField>

<ParamField type="integer">
  **size**: Video file size in bytes
</ParamField>

<ParamField type="integer">
  **progress**: Processing progress percentage (0-100)
</ParamField>

<ParamField type="string">
  **message**: Status message or error details
</ParamField>

<ParamField type="string">
  **createdAt**: ISO 8601 timestamp of video creation
</ParamField>

<ParamField type="string">
  **updatedAt**: ISO 8601 timestamp of last update
</ParamField>

## Polling for Video Completion

To wait for a video to complete, you can poll this endpoint:

```javascript Polling Example theme={null}
async function waitForVideoCompletion(videoId, maxWaitTime = 600000) {
  const pollInterval = 5000; // 5 seconds
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitTime) {
    const response = await fetch(
      `https://api.slidevid.ai/v1/video/${videoId}`,
      { headers: { 'x-api-key': API_KEY } }
    );
    const video = await response.json();

    console.log(`Status: ${video.status} (${video.progress}%)`);

    if (video.status === 'COMPLETED') {
      console.log(`Video ready! Download at: ${video.url}`);
      return video;
    }

    if (video.status === 'FAILED') {
      throw new Error(`Video failed: ${video.message}`);
    }

    // Wait before next poll
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }

  throw new Error('Video generation timeout');
}

const video = await waitForVideoCompletion('vid_abc123');
```

## Duration Calculation

Videos are rendered at **25 frames per second (fps)**.

To calculate duration in seconds:

```
durationInSeconds = durationInFrames / 25
```

For example:

* 6250 frames ÷ 25 fps = **250 seconds** (4:10 minutes)
* 3750 frames ÷ 25 fps = **150 seconds** (2:30 minutes)

## Error Responses

<Accordion title="404 - Video Not Found">
  The video ID doesn't exist or belongs to a different team
</Accordion>

<Accordion title="403 - Forbidden">
  The video doesn't belong to your team
</Accordion>

## Use Cases

<CardGroup cols={2}>
  <Card title="Check Processing Status" icon="hourglass">
    Monitor video generation progress
  </Card>

  <Card title="Download Completed Video" icon="download">
    Get the signed download URL when ready
  </Card>

  <Card title="Get Video Metadata" icon="info">
    Retrieve duration, size, and other details
  </Card>

  <Card title="Integration" icon="link">
    Integrate video generation into your workflow
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    Get all your videos
  </Card>

  <Card title="Create Video" icon="plus" href="/api-reference/video/create">
    Create a new video
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/video/{videoId}
openapi: 3.0.0
info:
  title: SlideVid API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.slidevid.ai
security:
  - ApiKeyAuth: []
paths:
  /v1/video/{videoId}:
    get:
      tags: []
      summary: Retrieve Video Details
      description: >-
        Get detailed information about a specific video including status,
        duration, and download URL
      operationId: getVideoDetails
      parameters:
        - name: videoId
          in: path
          description: Video ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Video details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique video identifier
                  name:
                    type: string
                    description: Video name/title
                  status:
                    type: string
                    enum:
                      - STARTED
                      - COMPLETED
                      - FAILED
                    description: Current video processing status
                  url:
                    type: string
                    description: >-
                      Signed URL to download the video (only available when
                      status is COMPLETED)
                  durationInFrames:
                    type: integer
                    description: Duration of the video in frames (at 25fps)
                  durationInSeconds:
                    type: number
                    description: >-
                      Duration of the video in seconds (calculated from
                      durationInFrames)
                  projectId:
                    type: string
                    nullable: true
                    description: Associated project ID if video belongs to a project
                  teamId:
                    type: string
                    description: Team ID that owns this video
                  thumbnail:
                    type: string
                    nullable: true
                    description: URL to video thumbnail image
                  size:
                    type: integer
                    description: Video file size in bytes
                  progress:
                    type: integer
                    minimum: 0
                    maximum: 100
                    description: Processing progress percentage (0-100)
                  message:
                    type: string
                    nullable: true
                    description: Status message or error details
                  createdAt:
                    type: string
                    format: date-time
                    description: Video creation timestamp
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
        '403':
          description: Video does not belong to the authenticated user
        '404':
          description: Video not found
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````