Overview

Relevant source files

• README.md
• pyproject.toml

Purpose and Scope

This document provides a high-level introduction to the ModelsLab Python SDK, the official Python interface to the ModelsLab API platform. The SDK enables programmatic access to AI-powered content generation services including image generation and editing, video synthesis, audio processing, 3D model creation, interior design, and deepfake operations.

This overview covers the SDK's architectural design, core components, and organizational structure. For detailed setup instructions, see Getting Started. For architectural deep dives, see Core Architecture. For API-specific documentation, see API Categories Reference or Provider Integrations.

Sources: README.md1-21 pyproject.toml1-10

What is the ModelsLab Python SDK

The ModelsLab Python SDK (modelslab_py) is a type-safe Python client library that provides structured access to the ModelsLab API platform. The SDK abstracts the complexity of HTTP communication, request validation, and response handling, allowing developers to generate AI content using simple Python objects.

The SDK serves two primary use cases:

1. Task-based API access via domain-organized API categories (e.g., "I need to generate a video")
2. Model-specific access via provider integrations (e.g., "I need to use Google's Imagen 4")

All operations support both synchronous and asynchronous execution patterns, with the async functionality available via an optional installation extra: pip install 'modelslab_py[async]'.

Sources: README.md19-32 pyproject.toml2-4 pyproject.toml11-17

High-Level Architecture

The SDK follows a layered architecture with clear separation of concerns:

Sources: README.md34-40 README.md42-51 README.md336-350

Core Components

Client Class

The Client class modelslab_py/core/client.py is the central HTTP communication handler. All API operations flow through this class, which manages:

• API key authentication
• Base URL configuration
• HTTP session management (sync via requests, async via aiohttp)
• Request/response handling

Users instantiate a single Client object and pass it to API category classes or provider classes.

Example instantiation:

Sources: README.md36-40

API Categories

API categories are domain-organized classes that group related operations. Each category is a Python class in modelslab_py/core/apis/:

Category	Module	Purpose	Example Operations
Community	core.apis.community	Community models and image generation	text_to_image, image_to_image, flux_2_dev
Video	core.apis.video	Video generation and manipulation	text_to_video, image_to_video
Audio	core.apis.audio	Audio synthesis and processing	text_to_speech, music_gen
Image_editing	core.apis.image_editing	Image post-processing	background_remover, super_resolution
Interior	core.apis.interior	Interior/exterior design	interior, room_decorator
Three_D	core.apis.three_d	3D model generation	text_to_3d, image_to_3d
DeepFake	core.apis.deepfake	Face and video manipulation	specific_face_swap, multiple_video_swap
Realtime	core.apis.realtime	Low-latency image generation	realtime_text_to_image

Each API category requires a Client instance and supports an optional enterprise flag that routes requests to enterprise endpoints.

Sources: README.md42-51 README.md351-360

Provider Integrations

Provider classes in modelslab_py/providers/ offer direct access to specific third-party models. Unlike API categories which abstract the model choice, providers give explicit control:

Provider	Module	Models Accessible
GoogleProvider	providers.google	Imagen 3, Imagen 4, Imagen 4.0 Ultra
BFLProvider	providers.bfl	Flux Pro 1.1, Flux Pro Ultra, Flux Kontext Pro
MinimaxProvider	providers.minimax	Hailuo 2.3, Hailuo 0.2 (text/image to video)
KlingAIProvider	providers.klingai	Kling V2.5 Turbo
SyncProvider	providers.sync	Lipsync 2
OpenAIProvider	providers.openai	Sora
RunwayProvider	providers.runway	Gen-4

Plus 8 additional providers (Alibaba, BytePlus, ElevenLabs, Inworld, Sonauto, etc.).

Sources: README.md258-350

Schema Validation Layer

All API methods require a Pydantic schema object from modelslab_py/schemas/. Schemas enforce type safety and validate inputs before network calls:

• Type checking: Ensures parameters match expected types
• Constraint validation: Enforces value ranges, formats, and required fields
• Serialization: Converts validated objects to API-compatible dictionaries

Example schema classes: Text2Video, BackgroundRemoverSchema, InteriorSchema, Hailuo23T2VSchema.

Sources: README.md64-67 README.md82-86 README.md272-274

SDK Organization

The SDK codebase is organized into these primary directories:

Sources: README.md56-90 README.md263-334

Typical Usage Flow

The following diagram illustrates the request lifecycle from user code to API response:

Sources: README.md74-90 README.md56-71

Key Features

Dual Execution Model

Every API method has both synchronous and asynchronous variants:

• Synchronous: Methods like text_to_video(), background_remover() use the requests library
• Asynchronous: Methods like async_text_to_video(), async_background_remover() use aiohttp (requires pip install 'modelslab_py[async]')

Async methods enable concurrent execution with asyncio.gather() for improved performance when making multiple API calls.

Sources: README.md210-257 pyproject.toml14-17

Enterprise vs Standard Endpoints

API categories support an enterprise boolean flag during initialization:

• enterprise=False (default): Routes to standard v6 endpoints (e.g., v6/video/text2video)
• enterprise=True: Routes to enterprise v1 endpoints (e.g., v1/enterprise/video/text2video)

Enterprise endpoints may offer different SLAs, rate limits, or exclusive features. See Enterprise vs Standard Endpoints for details.

Sources: README.md62 README.md80

Type Safety and Validation

All API parameters are validated using Pydantic v2 schemas before network transmission. This provides:

• IDE autocomplete and type hints
• Early error detection (client-side validation before API calls)
• Automatic serialization with None value filtering

Sources: pyproject.toml13 README.md64-67

Installation and Prerequisites

Basic Installation

With Async Support

Requirements

• Python: 3.9 or higher
• Core dependencies: pydantic ^2.11.3
• Optional dependencies: aiohttp ^3.9.0 (for async support)

The package is built with Poetry and published to PyPI as modelslab_py.

Sources: pyproject.toml11-17 README.md23-32

API Access and Authentication

All SDK operations require a valid ModelsLab API key, which is passed during Client initialization:

The Client automatically injects the API key into HTTP request headers for all subsequent operations. For information on obtaining an API key, visit the ModelsLab documentation.

Sources: README.md36-40

SDK Capabilities Summary

The SDK provides access to the following AI content generation capabilities:

Capability	API Categories	Provider Options
Image Generation	Community, Realtime	GoogleProvider, BFLProvider
Image Editing	Image_editing	-
Video Generation	Video	MinimaxProvider, KlingAIProvider, OpenAIProvider, RunwayProvider, AlibabaProvider
Audio Synthesis	Audio	ElevenLabsProvider, InworldProvider, SonautoProvider
3D Model Creation	Three_D	-
Interior Design	Interior	-
Face Manipulation	DeepFake	-
Lip Sync	-	SyncProvider
Multimodal Operations	-	BytePlusProvider

For task-based access where the specific model doesn't matter, use API Categories. For direct access to specific models, use Providers.

Sources: README.md42-51 README.md336-350

Next Steps

• Quick Start: See Getting Started for installation and basic usage examples
• Architecture Details: See Core Architecture for deep dives into the SDK's design
• API Reference: See API Categories Reference for detailed method documentation
• Provider Guide: See Provider Integrations for model-specific access patterns
• Advanced Usage: See Advanced Topics for async patterns, enterprise endpoints, and schema customization

Sources: README.md361-373