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

# Python SDK

> Install and use the official VidNavigator Python SDK to interact with the API.

## Installation

Install the SDK from PyPI using pip:

```bash theme={null}
pip install vidnavigator
```

## Initialization

Initialize the client with your API key. You can find your key in the [Developer Dashboard](https://vidnavigator.com/studio/api).

```python theme={null}
from vidnavigator import VidNavigatorClient

# It's recommended to load the API key from an environment variable
import dotenv
dotenv.load_dotenv()
client = VidNavigatorClient()
# Alternatively, you can pass it directly:
# client = VidNavigatorClient(api_key="YOUR_API_KEY")
```

You can also use a context manager to ensure the client is closed after use:

```python theme={null}
from vidnavigator import VidNavigatorClient

with VidNavigatorClient(api_key="YOUR_API_KEY") as vn:
    results = vn.analyze_video(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        query="What is the main topic discussed?")
    print(results)
```

***

## Online Videos

### Get Video Transcript

```python theme={null}
try:
    result = client.get_transcript(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    )
    print(result.data.video_info.title)
    print(result.data.transcript)
    # GET all the metadata in a dictionary
    print(result.data.video_info.model_dump())
    # Print data as a pretty string
    print(result.data.model_dump_json(indent=2))
except Exception as e:
    print(f"An error occurred: {e}")
```

### Transcribe a Video

```python theme={null}
try:
    result = client.transcribe_video(
        video_url="https://www.instagram.com/reel/C86ZvEaqRmo/"
    )
    print(result.data.video_info.title)
    # Print first segment of the transcript
    print(result.data.transcript[0].text)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Analyze a Video

```python theme={null}
try:
    analysis_data = client.analyze_video(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        query="What is the main topic of this song?"
    )
    print(analysis_data.transcript_analysis)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Search for Videos

```python theme={null}
try:
    search_results = client.search_videos(
        query="What are the best practices for React development?"
    )
    for video in search_results.data['results']:
        print(f"- {video['title']}")
except Exception as e:
    print(f"An error occurred: {e}")
```

***

## Files

### Upload a File

```python theme={null}
try:
    # Asynchronous upload (returns immediately)
    upload_response = client.upload_file(
        "path/to/your/video.mp4",
        wait_for_completion=False
    )
    print(f"File uploaded with ID: {upload_response['file_id']}")
except Exception as e:
    print(f"An error occurred: {e}")
```

### List Files

```python theme={null}
try:
    # Get the first 10 completed files
    files_response = client.get_files(limit=10, status="completed")
    for file_info in files_response.data.files:
        print(f"- {file_info.file_name} (ID: {file_info.file_id})")
except Exception as e:
    print(f"An error occurred: {e}")
```

### Get File Info

```python theme={null}
try:
    file_id = "your_file_id_here"
    file_details = client.get_file(file_id)
    print(file_details)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Get Temporary File URL to view it in the browser

```python theme={null}
try:
    file_id = "your_file_id_here"
    url_response = client.get_file_url(file_id)
    print(f"Temporary URL: {url_response['data']['file_url']}")
except Exception as e:
    print(f"An error occurred: {e}")
```

### Retry File Processing

```python theme={null}
try:
    file_id = "your_failed_file_id_here"
    retry_response = client.retry_file_processing(file_id)
    print(retry_response)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Cancel File Processing

```python theme={null}
try:
    file_id = "your_processing_file_id_here"
    cancel_response = client.cancel_file_upload(file_id)
    print(cancel_response)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Delete a File

```python theme={null}
try:
    file_id = "your_file_id_here"
    delete_response = client.delete_file(file_id)
    print(delete_response)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Analyze an Uploaded File

```python theme={null}
try:
    analysis_data = client.analyze_file(
        file_id="your_file_id_here",
        query="What are the key topics discussed in the first half?"
    )
    print(analysis_data.transcript_analysis)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Search Uploaded Files

```python theme={null}
try:
    search_results = client.search_files(
        query="Customer feedback on pricing"
    )
    for result in search_results.data['results']:
        print(f"- Found in: {result['file_name']}, Score: {result['relevance_score']}")
except Exception as e:
    print(f"An error occurred: {e}")
```

***

## System

### Get API Usage

```python theme={null}
try:
    usage_data = client.get_usage()
    print(usage_data)
except Exception as e:
    print(f"An error occurred: {e}")
```

### Health Check

```python theme={null}
try:
    health_status = client.health_check()
    print(health_status)
except Exception as e:
    print(f"An error occurred: {e}")
```

***

## Data Models

The SDK uses Pydantic models to represent the data returned by the API.

### Online Videos Data Models

<AccordionGroup>
  <Accordion title="TranscriptResponse">
    The response object from `get_transcript`. Contains `video_info` and `transcript` data.

    * **`data.video_info`**: A `VideoInfo` object with metadata about the video.
    * **`data.transcript`**: A list of `TranscriptSegment` objects.
  </Accordion>

  <Accordion title="AnalysisResponse">
    The response object from `analyze_video`.

    * **`data.video_info`**: A `VideoInfo` object.
    * **`data.transcript`**: A list of `TranscriptSegment` objects.
    * **`data.transcript_analysis`**: An `AnalysisResult` object.
  </Accordion>

  <Accordion title="VideoSearchResponse">
    The response object from `search_videos`.

    * **`data.results`**: A list of `VideoSearchResult` objects.
  </Accordion>
</AccordionGroup>

### Files Data Models

<AccordionGroup>
  <Accordion title="FilesListResponse">
    The response from `get_files`, containing a list of `FileInfo` objects.
  </Accordion>

  <Accordion title="FileResponse">
    The response from `get_file`, containing a `FileInfo` object and an optional `transcript`.
  </Accordion>

  <Accordion title="FileSearchResponse">
    The response from `search_files`, with a list of `FileSearchResult` objects.
  </Accordion>
</AccordionGroup>

## Exceptions

The Python SDK raises specific exceptions for different types of errors. All exceptions inherit from the base `VidNavigatorError`.

<AccordionGroup>
  <Accordion title="VidNavigatorError">
    The base exception for all SDK-related errors.
  </Accordion>

  <Accordion title="AuthenticationError">
    Raised when the API key is missing or invalid.
  </Accordion>

  <Accordion title="BadRequestError">
    Raised for `400 Bad Request` errors, typically due to invalid parameters.
  </Accordion>

  <Accordion title="AccessDeniedError">
    Raised for `403 Forbidden` errors, indicating insufficient permissions.
  </Accordion>

  <Accordion title="NotFoundError">
    Raised for `404 Not Found` errors when a resource does not exist.
  </Accordion>

  <Accordion title="RateLimitExceeded">
    Raised for `429 Too Many Requests` errors when you have exceeded your rate limit.
  </Accordion>

  <Accordion title="PaymentRequiredError">
    Raised for `402 Payment Required` errors when you have exceeded your usage quota.
  </Accordion>

  <Accordion title="ServerError">
    Raised for `5xx` server-side errors.
  </Accordion>
</AccordionGroup>

***

## More Information

For the complete source code and more examples, visit the [PyPI package](https://pypi.org/project/vidnavigator/) or the [GitHub repository](https://github.com/vidnavigator/vidnavigator-python).