Documentation

SDK Tutorial

Learn the core SDK workflows: upload, chat, and manage files

Prerequisites

Make sure you have installed the SDK and have your API key ready.

Async vs Sync

This guide shows async examples using AionVision. For sync applications (scripts, notebooks), use SyncAionVision instead - the API is identical, just without async/await. See the sync example at the bottom.

Single Import Pattern

All types, enums, and exceptions are available as class attributes. Just import AionVision and access everything via AionVision.DescriptionStatus, AionVision.UploadResult, AionVision.AuthenticationError, etc.

1. Initialize the Client

Create a client instance with your API key

import asyncio
from aion import AionVision

# Create and use the client with async context manager
async def main():
    async with AionVision(api_key="aion_...") as client:
        # Your code here
        pass

asyncio.run(main())

The client must be used within an async with block to ensure proper resource cleanup.

2. Upload an Image

Upload a local image and get an AI-generated description

async with AionVision(api_key="aion_...") as client:
    # Upload a single file and wait for AI description
    result = await client.upload_one("photo.jpg")

    print(f"Image ID: {result.image_id}")
    print(f"Description: {result.description}")
    print(f"Tags: {result.tags}")
    print(f"Visible Text: {result.visible_text}")
    print(f"Confidence: {result.confidence_score}")

3. Chat About Your Images

Ask questions about your uploaded images using the agentic chat

async with AionVision(api_key="aion_...") as client:
    # Use chat_session() for automatic session management
    async with client.chat_session() as session:
        # Ask about your images (uses all uploaded images as context)
        response = await session.send("What objects appear in my images?")
        print(f"Answer: {response.content}")
        print(f"Found {len(response.images or [])} relevant images")

        # Continue the conversation - session maintains context
        response2 = await session.send("Show me images with people")
        print(f"Answer: {response2.content}")

4. Manage Your Files

List and search your uploaded images

async with AionVision(api_key="aion_...") as client:
    # List recent files
    files = await client.files.list(limit=10)
    for f in files.files:
        print(f"{f.title}: {f.upload_description[:50]}...")

    # Search by text
    results = await client.files.list(search="damaged pole")
    print(f"Found {results.total_count} matching files")

    # Filter by tags
    tagged = await client.files.list(tags=["infrastructure"])

Complete Example

Putting it all together

import asyncio
from aion import AionVision

async def main():
    async with AionVision(api_key="aion_...") as client:
        # 1. Upload images (use upload_one for single files)
        print("Uploading images...")
        result1 = await client.upload_one("photo1.jpg")
        result2 = await client.upload_one("photo2.jpg")
        print(f"Uploaded {result1.image_id} and {result2.image_id}")

        # 2. Chat about them (use chat_session for session management)
        print("\nAsking about images...")
        async with client.chat_session() as session:
            response = await session.send("Describe what you see in my images")
            print(f"Response: {response.content}")

        # 3. List all files
        print("\nListing files...")
        files = await client.files.list(limit=10)
        for f in files.files:
            print(f"  - {f.title}: {f.upload_description[:50]}...")

asyncio.run(main())

Sync Client Example

For scripts, notebooks, or sync applications - no asyncio required

from aion import SyncAionVision

# Use 'with' instead of 'async with'
with SyncAionVision(api_key="aion_...") as client:
    # 1. Upload images (no await needed)
    print("Uploading images...")
    result1 = client.upload_one("photo1.jpg")
    result2 = client.upload_one("photo2.jpg")
    print(f"Uploaded {result1.image_id} and {result2.image_id}")

    # 2. Chat about them
    print("\nAsking about images...")
    with client.chat_session() as session:
        response = session.send("Describe what you see in my images")
        print(f"Response: {response.content}")

    # 3. List all files
    print("\nListing files...")
    files = client.files.list(limit=10)
    for f in files.files:
        print(f"  - {f.title}: {f.upload_description[:50]}...")

Important Notes

Thread Safety: SyncAionVision is NOT thread-safe. Do not share a single client instance across multiple threads. Create separate instances per thread if needed.

Streaming: send_stream() is only available with the async client. Use send() for non-streaming responses in sync mode.