Documentation
Upload Types
Types for upload operations and results
UploadResult
Result of a successful upload operation
python
@dataclass(frozen=True)class UploadResult: image_id: str # Unique identifier filename: str # Original filename description: Optional[str] = None # AI-generated description tags: Optional[list[str]] = None # AI-extracted tags visible_text: Optional[str] = None # OCR-extracted text text_regions: Optional[list[dict[str, Any]]] = None # Structured OCR entries with normalized (0-1) bounding boxes confidence_score: Optional[float] = None # Always null for descriptions; populated for extractions/rules description_status: DescriptionStatus = DescriptionStatus.PENDING # PENDING, COMPLETED, FAILED, etc. thumbnail_url: Optional[str] = None # URL to thumbnail created_at: Optional[datetime] = None # Upload timestamp description_error: Optional[str] = None # Error message if failed description_error_type: Optional[str] = None # Error classification description_is_retryable: Optional[bool] = None # Whether retry is possible # v2.0.0: populated by presigned/multipart completion; None for streaming uploads deduplicated: Optional[bool] = None # True if the file matched an existing content hash media_type: Optional[str] = None # "image" | "document" | "video" | "link" status: Optional[str] = None # "processing" | "completed" — upload status, not description object_key: Optional[str] = None # S3 storage key (presigned/multipart only)
# Properties @property def is_failed(self) -> bool: ... @property def is_completed(self) -> bool: ... @property def is_pending(self) -> bool: ...
# Serialization def to_dict(self, exclude_none: bool = True) -> dict[str, Any]: ...BatchUploadResults
List of UploadResult with convenience methods. Returned by upload() for batch uploads.
python
class BatchUploadResults(list): # Properties @property def has_failures(self) -> bool: ... @property def failed_count(self) -> int: ... @property def succeeded_count(self) -> int: ... @property def pending_count(self) -> int: ...
# Methods def failed(self) -> list[UploadResult]: ... def succeeded(self) -> list[UploadResult]: ... def pending(self) -> list[UploadResult]: ... def retryable(self) -> list[UploadResult]: ... def raise_on_failures(self) -> BatchUploadResults: ... def summary(self) -> str: ... # "3 succeeded, 1 failed"Tip
For single-file uploads, use client.files.upload() which returns UploadResult directly. Use client.files.upload_batch() for directories or lists.
QuotaInfo
Upload quota information
python
@dataclass(frozen=True)class QuotaInfo: can_proceed: bool # Whether upload can proceed requested: int # Number of uploads requested available: int # Uploads still available monthly_limit: int # Total monthly limit current_usage: int # Current month's usage message: Optional[str] = None # Quota status message max_batch_size: Optional[int] = None # Max files per batch (tier-dependent) prepaid_credits: int = 0 # Prepaid credit balance beyond monthly plan max_concurrent_uploads: Optional[int] = None # Max concurrent uploads (tier-dependent)Description Status Types
DescriptionStatus (Enum)
String enum representing the state of description generation. Re-exported at the top level as scopix.DescriptionStatus.
python
class DescriptionStatus(str, Enum): PENDING = "pending" QUEUED = "queued" PROCESSING = "processing" COMPLETED = "completed" FAILED = "failed" SKIPPED = "skipped"DescriptionResult
Structured description output. Imported from scopix.types.describe.
python
@dataclass(frozen=True)class DescriptionResult: operation_id: str # Unique operation identifier description: str # Main AI-generated description confidence_score: Optional[float] = None key_elements: Optional[list[str]] = None # Key elements detected in image tags: Optional[list[str]] = None visible_text: Optional[str] = None # OCR-extracted text text_regions: Optional[list[dict[str, Any]]] = None # OCR entries with normalized (0-1) bounding boxes analysis_level: str = "standard" provider_count: int = 1 # Number of AI providers used processing_time_ms: int = 0 metadata: Optional[dict[str, Any]] = NoneDescriptionErrorType
Classification of description generation errors for retry strategies
python
class DescriptionErrorType(str, Enum): TIMEOUT = "timeout" # AI provider timed out (retryable) RATE_LIMIT = "rate_limit" # Rate limit exceeded (retryable) VLM_ERROR = "vlm_error" # AI provider error (retryable) VALIDATION_ERROR = "validation" # Input validation failed (permanent) RESOURCE_LIMIT = "resource_limit" # Quota exceeded (permanent) UNKNOWN = "unknown" # Unclassified (not retryable)DescriptionFailure
Details about a failed description operation with error classification
python
@dataclass(frozen=True)class DescriptionFailure: image_id: str # ID of the image that failed error_message: str # Human-readable error message error_type: DescriptionErrorType # Classification of the error is_retryable: bool # Whether the operation can be retried filename: Optional[str] = None # Original filename raw_error: Optional[str] = None # Original error details
# Class methods @staticmethod def classify_error(error_msg: str) -> tuple[DescriptionErrorType, bool]: ... @classmethod def from_error_message(cls, image_id: str, error_msg: str, filename: Optional[str] = None) -> DescriptionFailure: ...