Python SDK Examples

First Call: Search and Download

Initialize a client and search for videos, then download one.

from gridbank_api import EnterpriseClient, EnterpriseAPIError

# Initialize client
client = EnterpriseClient(api_key="apik_your_key_here")

try:
    # Search for videos
    results = client.search_videos(
        q="morning skincare routine",
        sort="relevant",
        per_page=5
    )

    print(f"Found {len(results.videos)} videos (search_id: {results.search_id})")

    # Get the first result
    if results.videos:
        video = results.videos[0]
        print(f"\nTop result: {video.title}")
        print(f"Duration: {video.duration}s | Creator: {video.creator.name}")

        # Download the video
        download = client.download_video(
            video_id=video.id,
            expires_in=5,
            search_id=results.search_id  # track funnel
        )

        print(f"\nDownload URL: {download.url}")
        print(f"Expires: {download.expires_at}")

        # Check usage
        usage = client.usage_summary()
        print(f"\nUsage: {usage.downloads_this_period} downloads used")
        print(f"Tier: {usage.tier}")

except EnterpriseAPIError as e:
    print(f"HTTP {e.status_code}: {e.message}")
    if e.details:
        print(f"Details: {e.details}")
except Exception as e:
    print(f"Error: {e}")

Search with Filters

Search for videos with specific duration and theme:

# Find short nature documentaries
results = client.search_videos(
    q="nature documentary",
    duration_min=60,      # At least 1 minute
    duration_max=300,     # At most 5 minutes
    theme="nature",
    sort="popular",
    per_page=10
)

print(f"Found {len(results.videos)} short nature videos")

Fetch Video Details

Get full metadata for a video:

video = client.get_video(video_id="video_abc123")

print(f"Title: {video.title}")
print(f"Creator: {video.creator.name} (@{video.creator.username})")
if video.location:
    print(f"Location: {video.location.city}, {video.location.region}")
print(f"Duration: {video.duration}s")
print(f"Resolution: {video.width}x{video.height}")
if video.keywords:
    print(f"Keywords: {', '.join(video.keywords)}")

Batch Download Videos

Download multiple videos:

results = client.search_videos(q="nature", per_page=20)

for video in results.videos:
    try:
        download = client.download_video(
            video_id=video.id,
            expires_in=5,
            search_id=results.search_id
        )
        print(f"✓ {video.title} -> {download.url}")
    except EnterpriseAPIError as e:
        print(f"✗ {video.title} failed: {e.message}")

Check Quota Before Downloading

Verify you have remaining quota before large downloads:

usage = client.usage_summary()
print(f"Tier: {usage.tier}")
print(f"Downloads used: {usage.downloads_this_period}")
print(f"Period ends: {usage.lease_period_end}")

print(f"Period ends: {usage.lease_period_end}")

Pagination Example

Iterate through all search results sequentially (page 1 → 2 → 3, etc.) for consistent results:

page = 1
all_videos = []

while True:
    results = client.search_videos(
        q="nature",
        page=page,
        per_page=50
    )

    all_videos.extend(results.videos)
    print(f"Fetched {len(results.videos)} videos from page {page}")

    # Always check has_more before requesting next page
    if not results.has_more:
        break

    # Move to next page sequentially
    page += 1

print(f"Total videos collected: {len(all_videos)}")

Important: Always iterate sequentially from page 1. Jumping to arbitrary pages may return inconsistent results.

Error Handling Best Practices

from gridbank_api import EnterpriseClient, EnterpriseAPIError

client = EnterpriseClient(api_key="apik_...")

try:
    video = client.get_video(video_id="video_xyz")

except EnterpriseAPIError as e:
    # Handle by HTTP status code
    if e.status_code == 401:
        print("API key is invalid. Check your credentials.")
    elif e.status_code == 403:
        print("You don't have access. Upgrade your subscription.")
    elif e.status_code == 404:
        print("Video not found. Try searching first.")
    elif e.status_code == 429:
        print("Too many requests. Wait before retrying.")
    elif e.status_code == 422:
        for error in (e.details or []):
            print(f"Field {error['loc']}: {error['msg']}")
    else:
        print(f"HTTP {e.status_code}: {e.message}")

except Exception as e:
    # Handle unexpected errors
    print(f"Unexpected error: {e}")

Environment Setup

Store credentials securely:

# .env file
GRIDBANK_API_KEY=apik_your_key_here

import os
from gridbank_api import EnterpriseClient

api_key = os.getenv("GRIDBANK_API_KEY")
if not api_key:
    raise ValueError("GRIDBANK_API_KEY environment variable not set")

client = EnterpriseClient(api_key=api_key)

---

For more details, see: - Client Setup - Method Reference - Error Handling