### Complete Async API Example

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

This snippet shows how to initialize the async API, log in, search for GIFs by keyword, iterate through results, and download the first GIF found. Ensure you have the 'redgifs' library installed and an asyncio event loop running.

```python
import asyncio
from redgifs.aio import API
import redgifs

async def main():
    api = API()
    await api.login()
    
    try:
        # Search GIFs
        result = await api.search('3D', count=10)
        print(f"Found {result.total} GIFs, showing page {result.page} of {result.pages}")
        
        for gif in result.gifs:
            print(f"\nGIF: {gif.id}")
            print(f"  Creator: {gif.username}")
            print(f"  Views: {gif.views}, Likes: {gif.likes}")
            print(f"  Duration: {gif.duration}s")
        
        # Download first GIF
        if result.gifs:
            first_gif = result.gifs[0]
            hd_url = first_gif.urls.hd or first_gif.urls.sd
            bytes_written = await api.download(hd_url, f'{first_gif.id}.mp4')
            print(f"\nDownloaded {bytes_written} bytes")
            
    finally:
        await api.close()

if __name__ == '__main__':
    asyncio.run(main())
```

--------------------------------

### Example Usage of Async HTTP Methods

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Demonstrates how to use the asynchronous HTTP methods for login, getting a GIF, searching, and downloading. Requires asyncio to run.

```python
import asyncio
from redgifs.http import AsyncHttp

async def main():
    http = AsyncHttp()
    await http.login()
    
    # Get GIF
    response = await http.get_gif('abcxyz')
    print(response['gif']['id'])
    
    # Search
    search_result = await http.search('3D', order=Order.TRENDING, count=10, page=1)
    print(f"Found {search_result['total']} GIFs")
    
    # Download
    bytes_written = await http.download('https://redgifs.com/watch/abcxyz', 'video.mp4')
    print(f"Downloaded {bytes_written} bytes")
    
    await http.close()

asyncio.run(main())
```

--------------------------------

### Search Niches Example

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/03-types.md

Example of how to search for niches and iterate through the results to print niche names and subscriber counts.

```python
result = api.search_niches('anime')
for niche in result['niches']:
    print(f"{niche['name']}: {niche['subscribers']} subscribers")
```

--------------------------------

### Install redgifs Package

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Install the redgifs package using pip. This is the standard way to get the latest stable release.

```bash
pip install -U redgifs
```

--------------------------------

### Basic API Initialization

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Demonstrates how to create a basic instance of the API client. This is a starting point for most interactions.

```python
from redgifs import RedGifs

api = RedGifs()

```

--------------------------------

### Install Development Version

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Install the development version of redgifs directly from the GitHub repository using pip.

```bash
pip install -U git+https://github.com/scrazzz/redgifs
```

--------------------------------

### Get Creator Profile Information

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/09-quickstart.md

Search for a creator by username to get their profile details, including follower count and lists of their GIFs and images. Also shows how to get basic user info.

```python
api = redgifs.API()
api.login()

# Search creator by username
creator = api.search_creator('username123')
print(f"Creator: {creator.creator.username}")
print(f"Followers: {creator.creator.followers}")
print(f"GIFs: {len(creator.gifs)}")
print(f"Images: {len(creator.images)}")

# Get user info only
user = api.get_user('username123')
print(f"Created at: {user.creation_time}")
print(f"Verified: {user.verified}")

api.close()
```

--------------------------------

### Install Redgifs Package

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/00-START-HERE.md

Provides commands for installing the Redgifs Python package using pip, including both the standard and development versions.

```bash
# Standard install
pip install redgifs

# Development version
pip install git+https://github.com/scrazzz/redgifs
```

--------------------------------

### Sync API Setup and Search

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/00-START-HERE.md

Demonstrates synchronous API initialization, login, searching for GIFs, and closing the connection. Use this for blocking operations.

```python
import redgifs

api = redgifs.API()
api.login()
result = api.search('3D')
print(f"Found {result.total} GIFs")
api.close()
```

--------------------------------

### Proxy Authentication Usage Example

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/03-types.md

Demonstrates how to create a ProxyAuth instance and pass it to the API client constructor for proxy authentication.

```python
auth = redgifs.ProxyAuth(username='user', password='pass')
api = redgifs.API(proxy='http://proxy.com:8080', proxy_auth=auth)
```

--------------------------------

### Proxy Setup with Authentication

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Illustrates how to configure the API client to use an HTTP proxy with basic authentication. This is useful in restricted network environments.

```python
from redgifs import RedGifs

api = RedGifs(proxy="http://user:pass@host:port")

```

--------------------------------

### Async API Setup and Search

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/00-START-HERE.md

Demonstrates asynchronous API initialization, login, searching for GIFs, and closing the connection using async/await. Use this for non-blocking operations.

```python
import asyncio
from redgifs.aio import API

async def main():
    api = API()
    await api.login()
    result = await api.search('3D')
    print(f"Found {result.total} GIFs")
    await api.close()

asyncio.run(main())
```

--------------------------------

### Async Session Setup

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Demonstrates setting up an asynchronous HTTP client session for use with the RedGifs API. This is essential for non-blocking operations.

```python
from redgifs import RedGifs
from httpx import AsyncClient

async def main():
    async with AsyncClient() as session:
        api = RedGifs(session=session)
        # ... use api

import asyncio
asyncio.run(main())

```

--------------------------------

### Synchronous API Setup

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/09-quickstart.md

Initialize and log in to the synchronous redgifs API client. Ensure to close the API connection when done.

```python
import redgifs

api = redgifs.API()
api.login()

try:
    # Use API
    result = api.search('3D')
    print(f"Found {result.total} GIFs")
finally:
    api.close()
```

--------------------------------

### Initialize HTTP Client with Proxy Authentication

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Example of creating a ProxyAuth tuple and initializing the RedGifs API client with proxy details and authentication.

```python
import redgifs

auth = redgifs.ProxyAuth(username='proxyuser', password='proxypass')
api = redgifs.API(proxy='http://proxy.example.com:8080', proxy_auth=auth)
```

--------------------------------

### Custom HTTP Session Setup

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Shows how to initialize the API with a custom HTTP session, allowing for advanced configurations like proxies or custom headers.

```python
from redgifs import RedGifs
from httpx import AsyncClient

async def main():
    async with AsyncClient(proxy="http://user:pass@host:port") as session:
        api = RedGifs(session=session)
        # ... use api

import asyncio
asyncio.run(main())

```

--------------------------------

### Get Tag Suggestions

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Get autocomplete suggestions for a partial tag. The query parameter must be URL-encoded.

```HTTP
GET /v2/search/suggest?query={query}
```

--------------------------------

### Asynchronous API Setup

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/09-quickstart.md

Initialize and log in to the asynchronous redgifs API client using asyncio. Ensure to close the API connection when done.

```python
import asyncio
from redgifs.aio import API

async def main():
    api = API()
    await api.login()
    
    try:
        # Use API
        result = await api.search('3D')
        print(f"Found {result.total} GIFs")
    finally:
        await api.close()

asyncio.run(main())
```

--------------------------------

### Accessing RedGifs Library Version

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Demonstrates how to retrieve the installed version of the RedGifs library using `__version__` and `version_info` attributes.

```python
import redgifs
print(redgifs.__version__)  # '2.4.0'
print(redgifs.version_info)  # VersionInfo(major=2, minor=4, micro=0, releaselevel='final')
```

--------------------------------

### Get Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves a list of available tags.

```APIDOC
## Get Tags

### `api.get_tags()`

#### Description
Fetches a list of all available tags on the platform.

### Method
GET

### Endpoint
/v1/tags

### Parameters
None

### Response
#### Success Response (200)
- **tags** (List[string]) - A list of tag names.

### Response Example
```json
{
  "tags": ["funny", "cats", "memes"]
}
```
```

--------------------------------

### Get All Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve a list of all available tags on the platform. This endpoint does not require any query parameters.

```HTTP
GET /v1/tags
```

--------------------------------

### Construct and Print Route URLs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Examples of creating Route objects and printing their fully formed absolute URLs. Demonstrates usage with and without path parameters.

```python
from redgifs.http import Route

route = Route('GET', '/v2/gifs/{id}', id='abcxyz')
print(route.url)  # https://api.redgifs.com/v2/gifs/abcxyz

route = Route('GET', '/v1/tags')
print(route.url)  # https://api.redgifs.com/v1/tags
```

--------------------------------

### Example Usage of CreatorResult

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/03-types.md

Shows how to access and display information from a CreatorResult, such as the creator's username, total media count, and the number of GIFs and images returned.

```python
result = api.search_creator('username123')
print(f"Creator: {result.creator.username}")
print(f"Total media: {result.total}")
print(f"GIFs: {len(result.gifs)}, Images: {len(result.images)}")
```

--------------------------------

### Example Usage of SearchResult

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/03-types.md

Demonstrates how to process a SearchResult object, print pagination details and GIF information, and perform pagination to fetch the next page of results.

```python
result = api.search('3D', count=20)
print(f"Page {result.page}/{result.pages}, {len(result.gifs)} GIFs")
for gif in result.gifs:
    print(f"  {gif.id}: {gif.views} views")
# Pagination
next_result = api.search('3D', count=20, page=result.page + 1)
```

--------------------------------

### Get All Available Tags Asynchronously

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

Retrieve a list of all available tags on RedGifs. Each tag includes its information.

```python
async def get_tags(self) -> List[TagInfo]
```

--------------------------------

### Minimal Asynchronous API Usage

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Shows a basic asynchronous example using the redgifs library's async API client. This pattern is suitable for non-blocking operations.

```python
import asyncio
from redgifs.aio import API

async def main():
    api = API()
    await api.login()
    result = await api.search('3D')
    await api.close()

asyncio.run(main())
```

--------------------------------

### Example Usage of RedGifs Thumbnail Regex

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/07-utilities.md

Demonstrates how to use the compiled REDGIFS_THUMBS_RE to extract ID, type, and extension from a RedGifs thumbnail URL.

```python
import re
from redgifs.const import REDGIFS_THUMBS_RE

url = 'https://thumbs1.redgifs.com/abcxyz-mobile.mp4?for=192.168.1.1'
match = REDGIFS_THUMBS_RE.match(url)
if match:
    print(match.group('id'))    # 'abcxyz'
    print(match.group('type'))  # '-mobile'
    print(match.group('ext'))   # 'mp4'
```

--------------------------------

### Tag Autocomplete Suggestions

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/05-tags.md

Shows how to get tag suggestions as a user types. Handles cases where no matching tags are found.

```python
from redgifs import Tags

tags = Tags()

# User typing "w"
suggestions = tags.search('w')
print(f"Did you mean: {suggestions[:5]}")  # Show top 5 matches

# User types "wom"
try:
    suggestions = tags.search('wom')
    print(f"Suggestions: {suggestions}")
except InvalidTag:
    print("No matching tags")
```

--------------------------------

### Handle Rate Limiting with Python SDK

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Example of how to handle rate limiting (429 errors) when using the RedGifs Python SDK. It includes waiting and retrying logic.

```Python
import redgifs
import time

api = redgifs.API()
api.login()

try:
    result = api.search('3D')
except redgifs.HTTPException as e:
    if e.status == 429:
        print("Rate limited, waiting...")
        time.sleep(60)
        # Retry
finally:
    api.close()
```

--------------------------------

### Python Function Signature: Get Tag Suggestions

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Provides tag suggestions based on a partial query string. Returns a list of TagSuggestion objects.

```python
def get_tag_suggestions(self, query: str) -> List[TagSuggestion]
```

--------------------------------

### Initialize HTTP Client

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Demonstrates various ways to initialize the synchronous HTTP client. Includes default initialization, using a custom requests session, and configuring proxy settings with or without authentication.

```python
import requests
from redgifs.http import HTTP, ProxyAuth

# Default
http = HTTP()

# With custom session
session = requests.Session()
http = HTTP(session=session)

# With proxy
http = HTTP(proxy='http://proxy.example.com:8080')

# With proxy auth
auth = ProxyAuth('user', 'pass')
http = HTTP(proxy='http://proxy.example.com:8080', proxy_auth=auth)
```

--------------------------------

### Synchronous API Methods

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

The `redgifs.API` class offers over 15 synchronous methods for interacting with the RedGIFs API, including functionalities for login, searching, downloading, and more. Detailed parameter and return tables, along with usage examples, are available.

```APIDOC
## Synchronous API (`redgifs.API`)

### Description
Provides a synchronous interface to interact with the RedGIFs API. This class includes methods for common operations like authentication, searching for content, downloading media, and managing tags.

### Methods
- Constructor: Initializes the API client.
- login: Authenticates the user.
- search_gifs: Searches for GIFs.
- download_gif: Downloads a specific GIF.
- get_tags: Retrieves tag suggestions.
- ... (10+ additional methods)

### Parameters
Detailed parameter tables for each method are available in the `01-api-sync.md` file, specifying types, descriptions, and whether they are required or optional.

### Return Values
Return types for each method are documented, including specific data models like `GIF`, `Image`, and `SearchResult` as detailed in `03-types.md`.

### Examples
Usage examples for all synchronous operations are provided in `01-api-sync.md` and `09-quickstart.md`.
```

--------------------------------

### Get Tag Suggestions

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Get autocomplete suggestions for a partial tag query. This endpoint is useful for implementing tag search functionality.

```APIDOC
## GET /v2/search/suggest?query={query}

### Description
Get autocomplete suggestions for a partial tag.

### Method
GET

### Endpoint
/v2/search/suggest

### Query Parameters
- **query** (string) - Yes - Description: Partial tag name (URL-encoded).

### Response
#### Success Response (200)
- The response is an array of suggestion objects, where each object contains:
  - **text** (string) - The suggested tag text
  - **gifs** (integer) - The number of GIFs associated with the tag
  - **type** (string) - The type of suggestion (e.g., 'tag')
```

--------------------------------

### Get Trending Content

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/09-quickstart.md

Retrieve trending GIFs, images, and tags. Also shows how to get top content from the current week.

```python
api = redgifs.API()
api.login()

# Top 10 trending GIFs
trending_gifs = api.get_trending_gifs()
print(f"Top GIF: {trending_gifs[0].id} ({trending_gifs[0].views} views)")

# Top 10 trending images
trending_images = api.get_trending_images()

# Top tags
trending_tags = api.get_trending_tags()
for tag in trending_tags[:5]:
    print(f"{tag['name']}: {tag['count']} GIFs")

# Top this week
top_week = api.get_top_this_week(count=20)

api.close()
```

--------------------------------

### get_tag_suggestions

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Get suggestions for a partial tag query.

```APIDOC
## get_tag_suggestions

### Description
Get suggestions for a partial tag query.

### Method
GET

### Endpoint
/tags/suggestions

### Parameters
#### Query Parameters
- **query** (str) - Required - The partial tag query.

### Response
#### Success Response (200)
- **suggestions** (List[TagSuggestion]) - A list of tag suggestions.
```

--------------------------------

### Use NicheGifOrder Enum to Get GIFs from a Niche

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/10-enums.md

Demonstrates fetching GIFs from a specific niche using the NicheGifOrder enum to control the sorting of the results, such as trending or latest GIFs.

```python
import redgifs

api = redgifs.API()
api.login()

# Get GIFs from a niche
result = api.get_niche('niche_id', order=redgifs.NicheGifOrder.TRENDING)
result = api.get_niche('niche_id', order=redgifs.NicheGifOrder.LATEST)
result = api.get_niche('niche_id', order=redgifs.NicheGifOrder.HOT)

api.close()
```

--------------------------------

### Get User

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves information about a specific user by their username.

```APIDOC
## Get User

### `api.get_user(username)`

#### Description
Retrieves detailed information about a user given their username.

### Method
GET

### Endpoint
/v1/users/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.

### Response
#### Success Response (200)
- **user** (object) - Contains user details like username, name, etc.

### Response Example
```json
{
  "username": "example_user",
  "name": "Example User Name",
  "is_verified": true
}
```
```

--------------------------------

### get_user

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Get metadata about a user without their media. Requires a username.

```APIDOC
## Method: get_user

### Description
Get metadata about a user without their media.

### Method
GET (Assumed based on common API patterns for retrieving data)

### Endpoint
/users/{username} (Assumed based on common API patterns)

### Parameters
#### Path Parameters
- **username** (str) - Required - The user's username.

### Returns
- `User` - User profile information.
```

--------------------------------

### Get Niche GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves GIFs belonging to a specific niche.

```APIDOC
## Get Niche GIFs

### `api.get_niche(id)`

#### Description
Retrieves GIFs associated with a specific niche ID.

### Method
GET

### Endpoint
/v2/niches/{id}/gifs

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the niche.

### Response
#### Success Response (200)
- **gifs** (List[GIF]) - A list of GIF objects belonging to the specified niche.

### Response Example
```json
{
  "gifs": [
    {
      "id": "niche_gif_id_1",
      "urls": {
        "hd": "http://example.com/niche_hd1.mp4",
        "sd": "http://example.com/niche_sd1.mp4"
      },
      "description": "GIF from Niche"
    }
  ]
}
```
```

--------------------------------

### Initialize API

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Instantiate the synchronous API class. You can provide a pre-configured requests session, or proxy details for routing requests. If no session is provided, a new one is created.

```python
import redgifs

# Basic initialization
api = redgifs.API()
api.login()

# With custom session
import requests
session = requests.Session()
api = redgifs.API(session=session)
api.login()

# With proxy
api = redgifs.API(proxy='http://proxy.example.com:8080')
api.login()
```

--------------------------------

### Get Trending Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves a list of currently trending tags.

```APIDOC
## Get Trending Tags

### `api.get_trending_tags()`

#### Description
Fetches a list of tags that are currently trending.

### Method
GET

### Endpoint
/v2/search/trending

### Parameters
None

### Response
#### Success Response (200)
- **tags** (List[string]) - A list of trending tag names.

### Response Example
```json
{
  "tags": ["trending_tag_1", "trending_tag_2"]
}
```
```

--------------------------------

### Get Trending Images

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves a list of currently trending images.

```APIDOC
## Get Trending Images

### `api.get_trending_images()`

#### Description
Fetches a list of images that are currently trending.

### Method
GET

### Endpoint
/v2/explore/trending-images

### Parameters
None

### Response
#### Success Response (200)
- **images** (List[Image]) - A list of trending Image objects.

### Response Example
```json
{
  "images": [
    {
      "id": "trending_image_id_1",
      "url": "http://example.com/trending_image1.jpg",
      "description": "Trending Image 1"
    }
  ]
}
```
```

--------------------------------

### Get Trending Gifs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves a list of currently trending GIFs.

```APIDOC
## Get Trending Gifs

### `api.get_trending_gifs()`

#### Description
Fetches a list of GIFs that are currently trending.

### Method
GET

### Endpoint
/v2/explore/trending-gifs

### Parameters
None

### Response
#### Success Response (200)
- **gifs** (List[GIF]) - A list of trending GIF objects.

### Response Example
```json
{
  "gifs": [
    {
      "id": "trending_gif_id_1",
      "urls": {
        "hd": "http://example.com/trending_hd1.mp4",
        "sd": "http://example.com/trending_sd1.mp4"
      },
      "description": "Trending GIF 1"
    }
  ]
}
```
```

--------------------------------

### Configuration Options

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Explains how to configure the API client, including custom sessions, proxy support, and User-Agent customization.

```APIDOC
## API Configuration

### Description
Provides options for customizing the API client's behavior, such as using custom HTTP sessions, configuring proxy servers (with authentication), and setting a custom User-Agent string.

### Parameters
#### Initialization Parameters
- **session** (object) - Optional - A custom `requests.Session` or `aiohttp.ClientSession` object.
- **proxy** (string) - Optional - URL for an HTTP/HTTPS proxy.
- **proxy_auth** (tuple) - Optional - Tuple containing username and password for proxy authentication.
- **user_agent** (string) - Optional - Custom User-Agent string for requests.

### Request Example (Python Sync)
```python
import redgifs

api = redgifs.API(
    session=my_custom_session,
    proxy="http://user:pass@proxy.example.com:8080",
    user_agent="MyCustomApp/1.0"
)
```

### Request Example (Python Async)
```python
import redgifs
import aiohttp

async def main():
    session = aiohttp.ClientSession()
    api = redgifs.API(
        session=session,
        proxy="http://user:pass@proxy.example.com:8080",
        user_agent="MyCustomApp/1.0"
    )
    # ... use api ...
    await session.close()

asyncio.run(main())
```
```

--------------------------------

### Get GIF by ID

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Retrieves a specific GIF using its unique ID.

```APIDOC
## Get GIF by ID

### `api.get_gif(id)`

#### Description
Retrieves a specific GIF by its ID.

### Method
GET

### Endpoint
/v2/gifs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the GIF.

### Response
#### Success Response (200)
- **gif** (object) - Contains GIF details including URLs, descriptions, etc.

### Response Example
```json
{
  "id": "gif_id",
  "urls": {
    "hd": "http://example.com/hd.mp4",
    "sd": "http://example.com/sd.mp4"
  },
  "description": "A sample GIF"
}
```
```

--------------------------------

### Get Niche GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieves all GIFs from a specific niche, with options for ordering and pagination.

```APIDOC
## GET /v2/niches/{niche_id}/gifs

### Description
Retrieves all GIFs from a specific niche, with options for ordering and pagination.

### Method
GET

### Endpoint
/v2/niches/{niche_id}/gifs

#### Path Parameters
- **niche_id** (string) - Yes - The niche's unique identifier.

#### Query Parameters
- **order** (string) - Required - Sorting order. Possible values: `trending`, `latest`, `oldest`, `best`, `hot`
- **count** (integer) - Required - Number of results per page (1-100)
- **page** (integer) - Required - Page number (1+)

### Response
#### Success Response (200)
Standard search response with GIFs from the niche.
```

--------------------------------

### RedGIFs CLI Help

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Display the help message for the redgifs command-line interface, showing available options and usage.

```console
$ redgifs --help
Usage: redgifs [OPTIONS] [URLS]...

Options:
  -v, --version             Shows currently installed version.
  -q, --quality [sd|hd]     Video quality of GIF to download.  [default: hd]
  -f, --folder FOLDER_NAME  The folder to save the downloads to.
  -i, --input FILE_NAME     Download URLs from a newline seperated txt file.
  --images                  Download only images from a user profile.
  --help                    Show this message and exit.
```

--------------------------------

### Python: Async HTTP Client Constructor

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Initializes the asynchronous HTTP client using aiohttp. Supports optional session, proxy, and proxy authentication.

```python
def __init__(
    self,
    session: Optional[aiohttp.ClientSession] = None,
    *,
    proxy: Optional[str] = None,
    proxy_auth: Optional[ProxyAuth] = None,
) -> None
```

```python
import aiohttp
from redgifs.http import AsyncHttp, ProxyAuth

async def main():
    http = AsyncHttp()
    await http.login()
    
    # Make requests
    response = await http.get_gif('abcxyz')
    
    await http.close()

import asyncio
asyncio.run(main())
```

--------------------------------

### Get Temporary Token

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Obtains a temporary authentication token. This endpoint is public and used internally.

```APIDOC
## GET /v2/auth/temporary

### Description
Obtains a temporary authentication token. This endpoint is public and used internally.

### Method
GET

### Endpoint
/v2/auth/temporary

### Authentication
None (public endpoint)

### Response
#### Success Response (200)
- **token** (string) - The temporary authentication token.

### Response Example
```json
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```
```

--------------------------------

### Get Temporary Token Endpoint

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Obtain a temporary authentication token. This endpoint does not require authentication.

```HTTP
GET /v2/auth/temporary
```

--------------------------------

### Configuring Async API with a Custom aiohttp Session

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Illustrates initializing the asynchronous RedGifs API client with a custom `aiohttp.ClientSession` for advanced network configurations.

```python
import aiohttp
session = aiohttp.ClientSession()
api = redgifs.aio.API(session=session)
```

--------------------------------

### API Constructor

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

Initializes the asynchronous API client. It can optionally accept a pre-configured `aiohttp.ClientSession` or use its own. Proxy settings can also be configured.

```APIDOC
## API Constructor

### Description
Initializes the asynchronous API client. It can optionally accept a pre-configured `aioiohttp.ClientSession` or use its own. Proxy settings can also be configured.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
API(
    session: Optional[aiohttp.ClientSession] = None,
    *,
    proxy: Optional[str] = None,
    proxy_auth: Optional[ProxyAuth] = None,
) -> None
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| session | `Optional[aiohttp.ClientSession]` | None | Pre-configured aiohttp session. If not provided, a new one is created. |
| proxy | `Optional[str]` | None | Proxy URL for routing requests. |
| proxy_auth | `Optional[ProxyAuth]` | None | Proxy authentication credentials. |

### Request Example
```python
import asyncio
from redgifs.aio import API

async def main():
    api = API()
    await api.login()
    result = await api.search('3D')
    await api.close()

asyncio.run(main())
```
```

--------------------------------

### Get Available Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Fetches a list of all available tags on RedGifs, including their names and counts.

```python
def get_tags(self) -> List[TagInfo]
```

--------------------------------

### Initialize API Instance

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Instantiate the API class to interact with the RedGifs API. Optionally provide a requests.Session, proxy URL, or proxy authentication.

```python
from redgifs import API

api = API()
# Or with a session and proxy:
# api = API(session=requests.Session(), proxy="http://user:pass@host:port")
```

--------------------------------

### Get Trending GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Retrieves the top 10 trending GIFs. Requires API login.

```python
api = redgifs.API()
api.login()
trending = api.get_trending_gifs()
print(f"Top trending: {trending[0].id} with {trending[0].views} views")
```

--------------------------------

### Python Function Signature: Get User Info

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Retrieves profile information for a specific user by their username.

```python
def get_user(self, username: str, **params) -> UserInfo
```

--------------------------------

### Get Trending GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieves a list of the top 10 trending GIFs. No query parameters are required.

```APIDOC
## GET /v2/explore/trending-gifs

### Description
Retrieve top 10 trending GIFs.

### Method
GET

### Endpoint
/v2/explore/trending-gifs

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
Response schema is the same as the search endpoint, with up to 10 GIFs.
```

--------------------------------

### Configuring API with Proxy and Authentication

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Shows how to configure the RedGifs API client to use a proxy server with authentication credentials.

```python
auth = redgifs.ProxyAuth(username='user', password='pass')
api = redgifs.API(proxy='http://proxy.example.com:8080', proxy_auth=auth)
```

--------------------------------

### Get Top 10 Trending Images

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Retrieve the top 10 trending images currently on RedGifs.

```python
trending_images = api.get_trending_images()
```

--------------------------------

### Initialize Tags Instance

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/05-tags.md

Create a new Tags instance. Tags are loaded from 'tags.json' on first use.

```python
from redgifs import Tags

tags = Tags()
```

--------------------------------

### Get Top 10 Trending GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Retrieve the top 10 trending GIFs currently on RedGifs.

```python
trending_gifs = api.get_trending_gifs()
```

--------------------------------

### Configuring API with a Custom Requests Session

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/README.md

Demonstrates how to initialize the RedGifs API client with a pre-configured `requests.Session` object for custom connection pooling or settings.

```python
import requests
session = requests.Session()
api = redgifs.API(session=session)
```

--------------------------------

### Get GIF

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieves detailed information about a specific GIF using its unique identifier. Requires authentication.

```APIDOC
## GET /v2/gifs/{id}

### Description
Get detailed information about a single GIF.

### Method
GET

### Endpoint
/v2/gifs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Yes - The GIF's unique identifier.

#### Request Headers
- `Authorization: Bearer {temp_token}`
- `User-Agent: redgifs (https://github.com/scrazzz/redgifs {version}) Python/{python_version}`

### Response
#### Success Response (200)
- **gif** (object) - GIF metadata object
- **user** (object|null) - Creator's user info

#### Response Example
```json
{
  "gif": {
    "id": "string",
    "client_id": "string|null",
    "createDate": 1234567890,
    "hasAudio": true,
    "width": 640,
    "height": 480,
    "likes": 100,
    "tags": ["tag1", "tag2"],
    "verified": true,
    "views": 5000,
    "duration": 5.2,
    "published": true,
    "type": 1,
    "urls": {
      "sd": "https://thumbs1.redgifs.com/...",
      "hd": "https://thumbs2.redgifs.com/...",
      "poster": "https://thumbs1.redgifs.com/...",
      "thumbnail": "https://thumbs1.redgifs.com/...",
      "vthumbnail": "https://thumbs1.redgifs.com/..."
    },
    "userName": "creator_username",
    "avgColor": "#FF5733"
  },
  "user": {
    "creationtime": 1234567890,
    "username": "creator_username",
    "verified": true,
    ...
  }
}
```
```

--------------------------------

### API Constructor

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Initializes the synchronous RedGifs API client. It can be configured with a custom requests session, proxy, or proxy authentication.

```APIDOC
## Class: API

Synchronous interface to the RedGifs API. This is the main entry point for making API requests without async/await.

### Constructor

```python
API(
    session: Optional[requests.Session] = None,
    *,
    proxy: Optional[str] = None,
    proxy_auth: Optional[ProxyAuth] = None,
) -> None
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| session | `Optional[requests.Session]` | None | Pre-configured requests session. If not provided, a new session is created. |
| proxy | `Optional[str]` | None | Proxy URL for routing requests (e.g., `http://proxy.example.com:8080`). |
| proxy_auth | `Optional[ProxyAuth]` | None | Proxy authentication credentials as a `ProxyAuth` tuple. |

**Example:**

```python
import redgifs

# Basic initialization
api = redgifs.API()
api.login()

# With custom session
import requests
session = requests.Session()
api = redgifs.API(session=session)
api.login()

# With proxy
api = redgifs.API(proxy='http://proxy.example.com:8080')
api.login()
```
```

--------------------------------

### Configure Redgifs API with Proxy

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/09-quickstart.md

Initializes the redgifs API using proxy settings for network requests. Requires specifying the proxy URL and authentication details.

```python
import redgifs

auth = redgifs.ProxyAuth(username='user', password='pass')
api = redgifs.API(
    proxy='http://proxy.example.com:8080',
    proxy_auth=auth
)
api.login()
# Use API normally
api.close()
```

--------------------------------

### Python Function Signature: Get Trending Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Fetches trending search tags. Returns a TagsResponse object.

```python
def get_trending_tags(self) -> TagsResponse
```

--------------------------------

### Login to Async API

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

Shows how to log in to the asynchronous RedGifs API to obtain an authentication token. The method returns the API instance for chaining.

```python
api = API()
aoi = await api.login()
```

--------------------------------

### Get Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve a list of all available tags on the RedGifs platform, along with the count of media associated with each tag.

```APIDOC
## GET /v1/tags

### Description
Get all available tags.

### Method
GET

### Endpoint
/v1/tags

### Query Parameters
None

### Response
#### Success Response (200)
- **tags** (array) - Description: An array of tag objects, where each object contains:
  - **name** (string) - The name of the tag
  - **count** (integer) - The number of media items associated with the tag
```

--------------------------------

### Get Trending GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

Retrieves the top 10 trending GIFs. No authentication is strictly required for this public endpoint.

```python
api = API()
trending_gifs = await api.get_trending_gifs()
```

--------------------------------

### Python Function Signature: Get Trending Images

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Retrieves the top 10 trending images. Returns a TrendingImagesResponse object.

```python
def get_trending_images(self) -> TrendingImagesResponse
```

--------------------------------

### Download GIF with Fallback URL

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/00-START-HERE.md

Shows how to download a GIF, prioritizing the HD URL and falling back to the SD URL if HD is not available.

```python
gif = api.get_gif('id')
url = gif.urls.hd or gif.urls.sd  # Prefer HD
api.download(url, 'file.mp4')
```

--------------------------------

### Python Function Signature: Get Trending GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Fetches the top 10 trending GIFs. Returns a GifResponse object.

```python
def get_trending_gifs(self) -> GifResponse
```

--------------------------------

### login()

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Logs into RedGifs using a temporary token. This method must be called after initializing the API class for the library to function correctly.

```APIDOC
## login()

### Description
A method to login to RedGifs with a temporary token. You must use this method after initialising the [`API`](#redgifs.API) class for this library to function properly.

### Return type:
[`API`](#redgifs.API) - The properly initialised API class.
```

--------------------------------

### Python Function Signature: Get Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Fetches all available tags. The response object contains a list of tag information.

```python
def get_tags(self, **params: Any) -> TagsResponse
```

--------------------------------

### Import Core Library Components

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/INDEX.md

Import all necessary classes and enums from the synchronous redgifs library. This includes API clients, data models, and configuration options.

```python
from redgifs import API, GIF, Image, User, Order, MediaType, Tags
from redgifs.aio import API as AsyncAPI
```

--------------------------------

### Get User Info

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve a user's profile information without their media. Requires the username as a path parameter.

```HTTP
GET /v1/users/{username}
```

--------------------------------

### AsyncHttp Constructor

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/06-http.md

Asynchronous HTTP client using aiohttp. Mirrors the HTTP class but all methods are coroutines (async).

```APIDOC
## AsyncHttp Constructor

### Description
Initializes the asynchronous HTTP client.

### Parameters
#### Optional Parameters
- **session** (Optional[aiohttp.ClientSession]) - An existing aiohttp client session.
- **proxy** (Optional[str]) - The proxy URL to use for requests.
- **proxy_auth** (Optional[ProxyAuth]) - Proxy authentication details.
```

--------------------------------

### Get Top This Week Media

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve top media from the week. Requires specifying order, count, page, and type.

```HTTP
GET /v2/gifs/search?order=top7&count={count}&page={page}&type={type}
```

--------------------------------

### Download GIFs to Specific Folder with Quality Option

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Download GIFs to a specified folder and set the video quality to 'sd' using the command line.

```console
$ ls
Home    Downloads  Homework  Music
Backup  Documents  Videos    Games
$ redgifs https://redgifs.com/watch/xyz --quality sd --folder Homework
Downloading xyz...
Download complete
$ ls Homework
xyz.mp4
```

--------------------------------

### Get Trending Images

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve the top 10 trending images from the API. The response schema is similar to the search endpoint.

```HTTP
GET /v2/explore/trending-images
```

--------------------------------

### API Instance Initialization

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Initializes the RedGifs API instance. This is a prerequisite for using most other API methods. It can optionally accept a requests.Session object, a proxy URL, and proxy authentication details.

```APIDOC
## class redgifs.API(session=None, *, proxy=None, proxy_auth=None)

### Description
The API Instance to get information from the RedGifs API.

### Parameters
* **session** (Optional[`requests.Session`]) – A session object that can be provided to do the requests. If not provided, a new session object is created.
* **proxy** (Optional[`str`]) – A valid proxy URL.
* **proxy_auth** (Optional[[`ProxyAuth`](#redgifs.ProxyAuth)]) – The proxy auth to provide if the proxy requires it.
```

--------------------------------

### Get Niche GIFs

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Retrieves all GIFs from a specific niche identified by its ID. Allows sorting, result count, and pagination.

```python
def get_niche(
    self,
    niche_id: str,
    *, 
    order: NicheGifOrder = NicheGifOrder.TRENDING,
    count: int = 40,
    page: int = 1
) -> SearchResult
```

--------------------------------

### Get Trending Tags

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/01-api-sync.md

Retrieves currently trending search tags and their associated GIF counts. Requires API login.

```python
api = redgifs.API()
api.login()
tags = api.get_trending_tags()
for tag_info in tags:
    print(f"{tag_info['name']}: {tag_info['count']} GIFs")
```

--------------------------------

### Get Trending Images

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/02-api-async.md

Retrieves the top 10 trending still images. No authentication is strictly required for this public endpoint.

```python
api = API()
trending_images = await api.get_trending_images()
```

--------------------------------

### aio.API

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Initializes the asynchronous API client for RedGifs. Allows for custom aiohttp sessions and proxy configurations.

```APIDOC
## class redgifs.aio.API(session=None, *, proxy=None, proxy_auth=None)

### Description
The API Instance to get information from the RedGifs API.

### Parameters
#### Path Parameters
* **session** (aiohttp.ClientSession) - Optional - An `aiohttp.ClientSession` object that can be provided to do the requests. If not provided, a new session object is created.
* **proxy** (str) - Optional - A valid proxy URL.
* **proxy_auth** (ProxyAuth) - Optional - The proxy auth to provide if the proxy requires it.
```

--------------------------------

### Download Multiple GIFs via CLI

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Download multiple GIFs by providing their URLs as arguments to the redgifs command. Each URL will be downloaded sequentially.

```console
$ redgifs https://redgifs.com/watch/abc https://redgifs.com/watch/xyz https://redgifs.com/watch/def
Downloading abc...
Download complete

Downloading xyz...
Download complete

Downloading def...
Download complete
```

--------------------------------

### Asynchronous API Usage for GIF Search

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Demonstrates asynchronous usage of the redgifs API for searching GIFs. This requires importing the API from redgifs.aio and using await for operations.

```python
import asyncio
from redgifs.aio import API # note this

async def main():
    api = API()
    await api.login() # Login with temporary token
    response = await api.search('3D')
    print(response)
    await api.close()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
```

--------------------------------

### aio.login

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Logs into RedGifs using a temporary token within an asynchronous context. This method must be called after initializing the API class.

```APIDOC
## async login()

### Description
A method to login to RedGifs with a temporary token. You must use this method after initialising the `API` class for this library to function properly.

### Return type
API - The properly initialised API class.
```

--------------------------------

### Example Usage of RedGifs ID Regex

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/07-utilities.md

Demonstrates how to use the compiled REDGIFS_ID_RE to extract the GIF ID from a RedGifs URL.

```python
from redgifs.const import REDGIFS_ID_RE

url = 'https://thumbs1.redgifs.com/abcxyz-mobile.mp4'
match = REDGIFS_ID_RE.search(url)
if match:
    print(match.group('id'))  # 'abcxyz'
```

--------------------------------

### Iterate Through Search Results with Pagination

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/00-START-HERE.md

Illustrates how to loop through all pages of search results by checking the total number of pages and incrementing the page number.

```python
page = 1
while page <= result.pages:
    result = api.search('query', page=page, count=40)
    # Process result.gifs
    page += 1
```

--------------------------------

### Get Trending Tags

Source: https://github.com/scrazzz/redgifs/blob/main/docs/api.md

Retrieves trending searches on RedGifs. Returns a list of dictionaries, each containing a tag name and its associated count.

```python
from redgifs import RedGifs

client = RedGifs()

trending_tags = await client.get_trending_tags()
print(trending_tags)
```

--------------------------------

### Download All GIFs from User Profile via CLI

Source: https://github.com/scrazzz/redgifs/blob/main/README.md

Download all GIFs from a user's profile to a specified folder. The command indicates the progress of downloads.

```console
$ mkdir rg_vids
$ redgifs https://redgifs.com/users/usernamethatexists -f rg_vids
Downloaded 1/3 GIFs
Downloaded 2/3 GIFs
...
Downloaded 3/3 videos of user usernamethatexists to folder rg_vids sucessfully!
```

--------------------------------

### Construct API File URL

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/07-utilities.md

Builds an API file URL from a given media URL, typically used for downloading.

```python
from redgifs.utils import build_file_url

url = build_file_url('https://thumbs1.redgifs.com/abcxyz-mobile.mp4')
print(url)  # https://api.redgifs.com/v2/gifs/abcxyz/files/abcxyz.mp4
```

--------------------------------

### Get Niche GIFs Endpoint

Source: https://github.com/scrazzz/redgifs/blob/main/_autodocs/08-endpoints.md

Retrieve all GIFs associated with a specific niche using its ID. Supports ordering, count, and pagination.

```HTTP
GET /v2/niches/{niche_id}/gifs?order={order}&count={count}&page={page}
```