Managing Files

async with AionVision(api_key="aion_...") as client:
    # List recent files
    files = await client.files.list(limit=20)

    print(f"Total files: {files.total_count}")
    print(f"Has more: {files.has_more}")

    for f in files.files:
        print(f"{f.title or f.filename}: {f.upload_description[:50]}...")

# Search in descriptions and metadata
files = await client.files.list(
    search="damaged electrical equipment",
    search_mode="all"  # all | metadata | visible_text
)

for f in files.files:
    print(f"{f.title}: {f.upload_description}")

# Files must have ALL specified tags
files = await client.files.list(
    tags=["priority", "reviewed"]
)

# Only files with completed descriptions
files = await client.files.list(has_description=True)

# Only files without descriptions (pending or failed)
files = await client.files.list(has_description=False)

from datetime import datetime, timedelta

# Files from the last week
files = await client.files.list(
    date_from=datetime.now() - timedelta(days=7),
    date_to=datetime.now()
)

files = await client.files.list(
    sort_by="content_created_at",  # created_at | content_created_at | title | size_bytes
    sort_order="desc"  # desc | asc
)

offset = 0
limit = 50
all_files = []

while True:
    files = await client.files.list(
        limit=limit,
        offset=offset
    )
    all_files.extend(files.files)

    if not files.has_more:
        break

    offset += limit

print(f"Retrieved {len(all_files)} total files")

# Iterate through all files automatically
async for file in client.files.list_all(
    search="damaged",
    tags=["priority"]
):
    print(f"{file.title}: {file.upload_description[:50]}...")

details = await client.files.get(file_id="abc123...")

print(f"Title: {details.title}")
print(f"Size: {details.size_bytes} bytes")
print(f"Format: {details.format}")
print(f"Visible Text: {details.visible_text}")

# Access all descriptions
for desc in details.full_descriptions or []:
    print(f"\nDescription ({desc.verification_level}):")
    print(f"  Content: {desc.description}")
    print(f"  Confidence: {desc.confidence_score}")
    print(f"  Providers: {desc.providers_used}")

# Access image URLs
print(f"\nFull URL: {details.full_url}")
print(f"Thumbnail: {details.thumbnail_url}")
print(f"Medium: {details.medium_url}")

# Update title
result = await client.files.update(
    file_id="abc123...",
    title="Damaged Pole #42"
)

# Update tags
result = await client.files.update(
    file_id="abc123...",
    tags=["reviewed", "priority", "damage"]
)

# Update both
result = await client.files.update(
    file_id="abc123...",
    title="Equipment Inspection",
    tags=["inspection", "2024"]
)

print(f"Updated at: {result.updated_at}")

result = await client.files.delete(file_id="abc123...")

print(f"Deleted: {result.message}")
print(f"Deleted at: {result.deleted_at}")

result = await client.files.batch_delete(
    file_ids=["id1", "id2", "id3"]  # Max 100 files, no duplicates
)

print(f"Deleted: {result.summary['deleted']}")
print(f"Skipped: {result.summary['skipped']}")  # Files still processing
print(f"Failed: {result.summary['failed']}")

# Access individual results
for item in result.deleted:
    print(f"Deleted {item.id} at {item.deleted_at}")

# Available variants: tiny_64, small_256, medium_750, large_1024, original
url = await client.files.get_variant(
    file_id="abc123...",
    variant_type="medium_750"
)

print(f"Variant URL: {url}")

content = await client.files.download(file_id="abc123...")

with open("downloaded.jpg", "wb") as f:
    f.write(content)

result = await client.files.trigger_variant_generation(file_id="abc123...")

print(f"Job ID: {result['job_id']}")

files = await client.files.list(
    ids=["id1", "id2", "id3"],  # Max 500 IDs
)

@dataclass(frozen=True)
class UserFile:
    id: str
    size_bytes: int
    has_full_description: bool
    title: Optional[str]
    filename: Optional[str]
    thumbnail_url: Optional[str]
    upload_description: Optional[str]
    visible_text: Optional[str]
    tags: Optional[list[str]]
    created_at: Optional[datetime]
    content_created_at: Optional[datetime]  # From EXIF/metadata
    dimensions: Optional[dict[str, int]]    # {width, height}
    format: Optional[str]
    variant_status: Optional[str]           # pending/processing/completed/failed
    variant_count: Optional[int]
    medium_url: Optional[str]
    full_url: Optional[str]                 # None if variants not yet generated
    blur_hash: Optional[str]                # For blur-up placeholder
    description_status: Optional[str]
    description_error: Optional[str]        # Error if description failed
    content_type: Optional[str]             # MIME type (image/jpeg, video/mp4)
    media_type: Optional[str]               # "image" or "video"
    # Video-specific fields
    video_metadata: Optional[dict]          # Duration, resolution, codecs, etc.
    video_analysis_status: Optional[str]
    video_analysis_job_id: Optional[str]
    video_url: Optional[str]
    scene_count: Optional[int]
    has_audio_transcript: Optional[bool]

@dataclass(frozen=True)
class UserFileDetails:
    id: str
    object_key: str
    size_bytes: int
    content_type: str
    hash: str
    title: Optional[str]
    tags: Optional[list[str]]
    dimensions: Optional[dict[str, int]]
    format: Optional[str]
    full_url: Optional[str]                 # 1024px variant, None if not yet generated
    thumbnail_url: Optional[str]
    medium_url: Optional[str]
    original_url: Optional[str]             # Always available as fallback
    upload_description: Optional[str]
    visible_text: Optional[str]
    description_generated_at: Optional[datetime]
    description_status: Optional[str]       # pending | processing | completed | failed
    full_descriptions: Optional[list[FullDescription]]
    processing_history: Optional[list[ProcessingHistory]]
    created_at: Optional[datetime]
    updated_at: Optional[datetime]
    content_created_at: Optional[datetime]  # From EXIF/video metadata
    upload_method: Optional[str]            # DIRECT | POST
    original_filename: Optional[str]
    variant_status: Optional[str]           # pending/processing/completed/failed
    variant_count: Optional[int]
    blur_hash: Optional[str]