Documentation

Code Examples

Ready-to-use examples in popular programming languages

Before You Start

Replace scopix_your_api_key with your actual API key from the dashboard.

Quick Start: Analyze an Image

One API call to upload, describe, and extract text

cURL

bash

curl -X POST https://api.scopix.ai/api/v2/images/analyze \
  -H "Authorization: Bearer scopix_your_api_key" \
  -F "file=@photo.jpg"

Python

python

import requests

response = requests.post(
    "https://api.scopix.ai/api/v2/images/analyze",
    headers={"Authorization": "Bearer scopix_your_api_key"},
    files={"file": open("photo.jpg", "rb")}
)
result = response.json()
print(f"Description: {result['description']}")
print(f"Tags: {result['tags']}")
print(f"Status: {result['status']}")

Async with Polling

python

import requests, time

API_KEY = "scopix_your_api_key"
BASE = "https://api.scopix.ai/api/v2"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Submit async
resp = requests.post(
    f"{BASE}/images/analyze/async",
    headers=headers,
    files={"file": open("photo.jpg", "rb")}
)
job = resp.json()
print(f"Job ID: {job['job_id']}")

# Poll for results
while True:
    status = requests.get(
        f"{BASE}/job/{job['job_id']}",
        headers=headers
    ).json()

    if status["status"] in ("completed", "failed"):
        break
    time.sleep(2)

for r in status["results"]:
    print(f"Description: {r['description']}")
    print(f"Tags: {r['tags']}")

Python

Using the requests library

Upload Image with Auto-Description

python

import requests

API_KEY = "scopix_your_api_key"
BASE_URL = "https://api.scopix.ai/api/v2"

# Upload and describe in a single request
with open("product.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/files/upload",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": ("product.jpg", f, "image/jpeg")},
        data={"auto_describe": "true"}
    )

result = response.json()
print(f"Image ID: {result['image_id']}")
print(f"Status: {result['status']}")
print(f"Analysis started: {result['analysis_started']}")

Multi-File Upload with Session Tracking

python

import requests
import time

API_KEY = "scopix_your_api_key"
BASE_URL = "https://api.scopix.ai/api/v2"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Upload multiple files in a single batch request
files = [
    ("files", ("image1.jpg", open("image1.jpg", "rb"), "image/jpeg")),
    ("files", ("image2.jpg", open("image2.jpg", "rb"), "image/jpeg")),
]

response = requests.post(
    f"{BASE_URL}/files/upload/batch",
    headers=headers,
    files=files,
)
batch_data = response.json()
session_id = batch_data["session_id"]
print(f"Session ID: {session_id}")
print(f"Accepted: {batch_data['accepted_files']}/{batch_data['total_files']} files")

# For small batches (<=5 files), immediate_results is included
if batch_data.get("immediate_results"):
    for img in batch_data["immediate_results"]:
        print(f"  {img['filename']}: {img['status']}")
else:
    # Poll session status for larger batches
    while True:
        status_resp = requests.get(
            f"{BASE_URL}/files/sessions/{session_id}/status",
            headers=headers
        )
        status = status_resp.json()
        pct = status.get("progress_percentage", 0)
        print(f"Status: {status['status']} - Progress: {pct:.0f}%")

        if status["status"] in ["completed", "failed", "cancelled"]:
            break
        time.sleep(2)

cURL

Command line examples

Upload Image

bash

# Single file upload
curl -X POST https://api.scopix.ai/api/v2/files/upload \
  -H "Authorization: Bearer scopix_your_api_key" \
  -F "file=@image.jpg"

# Batch upload (multiple files)
curl -X POST https://api.scopix.ai/api/v2/files/upload/batch \
  -H "Authorization: Bearer scopix_your_api_key" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg" \
  -F "tags=inspection,site"

Error Handling

python

import requests
import time

def upload_with_retry(file_path, max_retries=3):
    """Upload a file with automatic retry and error handling."""
    API_KEY = "scopix_your_api_key"
    BASE_URL = "https://api.scopix.ai/api/v2"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    for attempt in range(max_retries):
        try:
            with open(file_path, "rb") as f:
                response = requests.post(
                    f"{BASE_URL}/files/upload",
                    headers=headers,
                    files={"file": f},
                )

            if response.status_code == 200:
                result = response.json()
                print(f"Success: {result['image_id']}")
                return result

            elif response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                print(f"Rate limited, waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue

            elif response.status_code == 413:
                print("File too large — maximum size is 100MB")
                return None

            else:
                error = response.json().get('detail', response.text)
                print(f"Error {response.status_code}: {error}")
                return None

        except requests.exceptions.RequestException as e:
            print(f"Request failed (attempt {attempt + 1}/{max_retries}): {e}")
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Retrying in {wait_time} seconds...")
                time.sleep(wait_time)
                continue
            raise