Documentation

SDK Reference

Complete API reference for the Scopix Python SDK

Reference Documentation

This section provides a comprehensive reference of all classes, methods, and types in the SDK. For tutorials and guides, see the SDK Guide.

Quick Reference

Section	Description
Client	Main Scopix client class and convenience methods
Resources	Sub-client resources (uploads, files, chats, etc.)
Types	All dataclasses and response types
Exceptions	Exception hierarchy and error types

class Scopix

Main async client for the Scopix Vision AI API

Constructor

python

Scopix(
    api_key: str,
    *,
    base_url: str = "https://api.scopix.ai/api/v2",
    timeout: float = 300.0,
    max_retries: int = 3,
    retry_delay: float = 1.0,
    polling_interval: float = 2.0,
    polling_timeout: float = 360.0,
    tenant_id: Optional[str] = None,
    proxy_url: Optional[str] = None,
    enable_tracing: bool = False,
)

Parameters

Name	Type	Default	Description
api_key	str	required	Your Scopix API key (starts with scopix_)
base_url	str	production URL	API base URL
timeout	float	300.0	Request timeout in seconds
max_retries	int	3	Maximum retry attempts for transient failures
retry_delay	float	1.0	Initial delay between retries (exponential backoff)
polling_interval	float	2.0	Interval for polling operations (auto-describe)
polling_timeout	float	360.0	Maximum time to wait for polling operations
tenant_id	Optional[str]	None	Tenant ID for multi-tenant deployments
proxy_url	Optional[str]	None	Proxy URL (http or https)
enable_tracing	bool	False	Enable OpenTelemetry tracing

Context Manager Usage

The client must be used as an async context manager

python

async with Scopix(api_key="scopix_...") as client:
    result = await client.files.upload("photo.jpg")
    print(result.description)

Factory Methods

from_env()

Create a client from environment variables

python

@classmethod
def from_env(**overrides) -> Scopix

Reads configuration from SCOPIX_* environment variables. See Environment Variables for details.

Upload Methods

Unified file upload via client.files — images, documents, and videos.

client.files.upload()

Upload a single file. Strategy auto-selected by size.

python

async def upload(
    file: Union[str, Path, bytes],
    *,
    filename: Optional[str] = None,
    content_type: Optional[str] = None,
    strategy: Literal["auto", "streaming", "presigned", "multipart"] = "auto",
    title: Optional[str] = None,
    tags: Optional[list[str]] = None,
    folder_id: Optional[str] = None,
    project_id: Optional[str] = None,
    content_category: Union[ContentCategory, str, None] = None,
    storage_target: Union[StorageTarget, str] = StorageTarget.DEFAULT,
    skip_duplicates: bool = False,
    auto_describe: bool = True,
    on_progress: Optional[Callable[[UploadProgressEvent], None]] = None,
) -> UploadResult

client.files.upload_batch()

Upload a directory or list. Directory paths auto-expand to all supported media.

python

async def upload_batch(
    files: Union[str, Path, list[Union[str, Path, bytes]]],
    *,
    recursive: bool = True,
    include_hidden: bool = False,
    filenames: Optional[list[str]] = None,
    title: Optional[str] = None,
    tags: Optional[list[str]] = None,
    folder_id: Optional[str] = None,
    project_id: Optional[str] = None,
    content_category: Union[ContentCategory, str, None] = None,
    storage_target: Union[StorageTarget, str] = StorageTarget.DEFAULT,
    skip_duplicates: bool = False,
    auto_describe: bool = True,
) -> BatchUploadResults

chat_session()

Create a chat session context manager

python

def chat_session(
    *,
    title: Optional[str] = None,
    image_ids: Optional[list[str]] = None,
    use_all_images: bool = True,
    auto_close: bool = True,
) -> ChatSessionContext

chat()

Send a message to an existing session and get a complete response

python

async def chat(
    message: str,
    *,
    session_id: str,
    force_detailed_analysis: bool = False,
) -> ChatResponse

chat_stream()

Send a message and stream response tokens as they arrive

python

async def chat_stream(
    message: str,
    *,
    session_id: str,
    force_detailed_analysis: bool = False,
) -> AsyncIterator[ChatToken]

pipeline()

Create a pipeline builder for multi-step agent workflows

python

def pipeline() -> Pipeline

Returns a Pipeline builder. Chain agent steps and call .run() to execute.

Resource Properties

Access to sub-client resources for advanced operations

Property	Type	Description
client.chats	ChatResource	Chat session management
client.files	FilesResource	File management operations
client.colors	ColorsResource	Color analysis and search (automatic on upload)
client.settings	SettingsResource	Organization settings (custom S3)
client.tenant	TenantResource	Tenant management
client.audit	AuditResource	Audit log operations
client.agent_search	AgentSearchResource	Standalone AI-powered search
client.agent_operations	AgentOperationsResource	AI-powered synthesis, analysis, and organization
client.folders	FoldersResource	Folder management and organization
client.cloud_storage	CloudStorageResource	Cloud storage import/export (Google Drive)

Continue

Resources Reference

All sub-client resources and their methods

Types Reference

All dataclasses and response types

Exceptions Reference

Exception hierarchy and error handling