Python SDK Methods

All Enterprise API methods are available through the EnterpriseClient instance. Methods use Python naming conventions (snake_case) and return typed dataclass models.

search_videos()

Query the GridBank video library with full-text search. Supports filtering by duration and category, with multiple sort options for relevance, popularity, and recency.

result = client.search_videos(
    q="skincare morning routine",
    sort="relevant",
    page=1,
    per_page=15,
    duration_min=None,
    duration_max=None,
    theme=None
)

Parameters:

• q (str, required): Search query (1–200 characters)
• sort (str, default "relevant"): Sort by "relevant", "popular", or "recent"
• page (int, default 1): Page number for pagination
• per_page (int, default 15): Results per page (1–80)
• duration_min (int | None): Minimum duration in seconds
• duration_max (int | None): Maximum duration in seconds
• theme (str | None): Content category filter

Returns:

class VideoListResponse:
    search_id: str             # Unique search session ID
    page: int                  # Current page number
    per_page: int              # Results per page
    has_more: bool             # True if more pages exist
    videos: list[Video]        # Array of matching videos

Errors: 400, 401, 422, 429, 500

Example:

result = client.search_videos(q="nature", sort="relevant", page=1, per_page=15)
print(f"Found {len(result.videos)} videos")
for video in result.videos:
    print(f"  {video.id}: {video.title}")

---

get_video()

Fetch complete metadata for a single video by ID, including creator details, dimensions, and licensing information. Requires active subscription.

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

Parameters:

• video_id (str, required): Video identifier

Returns:

class Video:
    id: str                        # Video ID
    creator: Creator               # Creator metadata
    title: str | None              # Title
    description: str | None        # Long-form description
    duration: float | None         # Duration in seconds
    width: int | None              # Width in pixels
    height: int | None             # Height in pixels
    url: str | None                # Preview URL
    thumbnail: str | None          # Thumbnail URL
    location: Location | None      # Location metadata
    keywords: list[str] | None     # Associated keywords

Errors: 401, 403, 404, 429, 500

Example:

video = client.get_video(video_id="video_abc123")
print(f"{video.title} ({video.duration}s)")
print(f"By {video.creator.name}")
print(f"Keywords: {', '.join(video.keywords)}")

---

download_video()

Generate a time-limited, signed download URL for the original video file. Perfect for integrating video downloads into your application. Requires active subscription.

download = client.download_video(
    video_id="video_abc123",
    expires_in=5,
    search_id=None
)

Parameters:

• video_id (str, required): Video identifier
• expires_in (int, default 5): URL expiration in minutes (1–5)
• search_id (str | None): Search session ID for analytics

Returns:

class DownloadResult:
    video_id: str              # Video ID
    url: str                   # Signed download URL
    expires_at: datetime       # Expiration timestamp
    file_size: int             # File size in bytes
    format: str                # File format (e.g. "mp4")

Errors: 401, 403, 404, 429, 500

Example:

download = client.download_video(
    video_id="video_abc123",
    expires_in=5,
    search_id=results.search_id
)
print(f"Download expires at: {download.expires_at}")
print(f"URL: {download.url}")

---

usage_summary()

Check your account's current subscription tier, download quota, and billing period. Use this to monitor your usage and determine when to upgrade your plan.

usage = client.usage_summary()

Parameters: None

Returns:

class UsageSummary:
    customer_id: str               # Customer identifier
    tier: str                      # Subscription tier
    lease_period_start: datetime   # Period start timestamp
    lease_period_end: datetime     # Period end timestamp
    downloads_this_period: int     # Downloads used this billing period
    active_collections_count: int  # Number of active collections
    wildcard_enabled: bool         # Whether wildcard access is enabled
    top_videos: list[TopVideo]     # Most downloaded videos this period

Errors: 401, 429, 500

Example:

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

---

Exception Handling

All methods raise EnterpriseAPIError on errors:

from gridbank_api import EnterpriseAPIError

try:
    video = client.get_video(video_id="invalid")
except EnterpriseAPIError as e:
    print(f"HTTP {e.status_code}: {e.message}")
    if e.details:
        print(f"Details: {e.details}")

---

Next Step

See end-to-end examples.