Scopix

Documentation

SDK Tutorial

Learn the core SDK workflows: upload, annotate, search, and chat

Prerequisites

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

Async vs Sync

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

Imports

Core types, enums, and exceptions are importable directly from scopix: from scopix import Scopix, UploadResult, DescriptionStatus, AuthenticationError. Feature-specific types live in submodules, e.g. from scopix.types.usage import UsageSummary.

1. Initialize the Client

Create a client instance with your API key

python
import asyncio
from scopix import Scopix


# Create and use the client with async context manager
async def main():
    async with Scopix(api_key="scopix_...") 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 & Annotate

Upload a local image and get structured annotations automatically

python
async with Scopix(api_key="scopix_...") as client:
    # Upload a single file and wait for AI description
    result = await client.files.upload("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}")

3. Search Your Annotations

Find images by what's in them using natural language

python
async with Scopix(api_key="scopix_...") as client:
    # Search across all your annotated images
    result = await client.agent_search.images("damaged equipment")


    print(f"Found {result.count} matching images")
    print(f"Summary: {result.summary}")


    for img in result.results[:5]:
        print(f"- {img.filename}: score={img.score:.2f}")
        print(f"  Description: {img.description[:80]}...")

4. Chat About Your Images

Ask questions about your uploaded images using the agentic chat

python
async with Scopix(api_key="scopix_...") 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}")

5. Manage Your Files

List and browse your annotated files

python
async with Scopix(api_key="scopix_...") as client:
    # List recent files
    files = await client.files.list(limit=10)
    for f in files.items:
        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

python
import asyncio
from scopix import Scopix


async def main():
    async with Scopix(api_key="scopix_...") as client:
        # 1. Upload images
        print("Uploading images...")
        result1 = await client.files.upload("photo1.jpg")
        result2 = await client.files.upload("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.items:
            print(f"  - {f.title}: {f.upload_description[:50]}...")


asyncio.run(main())

Sync Client Example

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

python
from scopix import SyncScopix


# Use 'with' instead of 'async with'
with SyncScopix(api_key="scopix_...") as client:
    # 1. Upload images (no await needed)
    print("Uploading images...")
    result1 = client.files.upload("photo1.jpg")
    result2 = client.files.upload("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.items:
        print(f"  - {f.title}: {f.upload_description[:50]}...")

Important Notes

Thread Safety: SyncScopix 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.

What's Next?

Uploading Images

Learn about batch uploads and progress callbacks

Uploading Documents

PDF, DOCX, TXT, MD with chunking and embedding

Uploading Videos

Multipart video uploads with scene-level AI analysis and search

Semantic Search

Advanced search with filters, folders, and document search

Agentic Chat

Explore streaming and session management

Error Handling

Handle errors gracefully in production

Type Reference

Explore all response types