Documentation

Environment Variables

Configure the SDK using environment variables for secure and flexible deployments

Best Practice

Using environment variables for configuration keeps sensitive data like API keys out of your code and allows different settings for development, staging, and production environments.

Using from_env() Factory Method

The recommended way to use environment variables is with the from_env() factory method

from aion import AionVision, SyncAionVision

# Async client - loads all config from environment variables
async with AionVision.from_env() as client:
    result = await client.upload_one("photo.jpg")

# Sync client - same pattern
with SyncAionVision.from_env() as client:
    result = client.upload_one("photo.jpg")

# Override specific values while using env vars for the rest
async with AionVision.from_env(timeout=60.0) as client:
    result = await client.upload_one("photo.jpg")

Environment Variables Reference

All supported environment variables

Variable	Type	Default	Description
`AIONVISION_API_KEY`	string	Required	Your Aionvision API key
`AIONVISION_BASE_URL`	string	Production API	API base URL
`AIONVISION_TIMEOUT`	float	300.0	Request timeout in seconds
`AIONVISION_MAX_RETRIES`	int	3	Maximum retry attempts
`AIONVISION_RETRY_DELAY`	float	1.0	Initial retry delay (exponential backoff)
`AIONVISION_POLLING_INTERVAL`	float	2.0	Interval between status polls
`AIONVISION_POLLING_TIMEOUT`	float	360.0	Maximum polling wait time
`AIONVISION_TENANT_ID`	string	None	Tenant ID for multi-tenant deployments
`AIONVISION_PROXY_URL`	string	None	Proxy URL (http, https, or socks5)
`AIONVISION_ENABLE_TRACING`	bool	false	Enable OpenTelemetry tracing. Accepted values: `true`, `1`, `yes`, `on` (case-insensitive)

Setting Environment Variables

Set variables in your shell or system environment

# Linux / macOS
export AIONVISION_API_KEY="aion_your_api_key_here"
export AIONVISION_TIMEOUT="60.0"

# Windows PowerShell
$env:AIONVISION_API_KEY = "aion_your_api_key_here"
$env:AIONVISION_TIMEOUT = "60.0"

Using .env Files

Install python-dotenv

For local development, use a .env file with the optional dotenv extra

# Install SDK with dotenv support
pip install "aion[dotenv]" --extra-index-url https://aion:YOUR_API_KEY@api.aionvision.tech/api/v2/sdk/simple/

Create .env File

Create a .env file in your project root

# .env file
AIONVISION_API_KEY=aion_your_api_key_here
AIONVISION_TIMEOUT=60.0
AIONVISION_MAX_RETRIES=5
AIONVISION_RETRY_DELAY=0.5
AIONVISION_POLLING_INTERVAL=3.0
AIONVISION_POLLING_TIMEOUT=180.0

Load .env in Your Code

Use the load_dotenv() helper before creating the client

from aion import load_dotenv, AionVision

# Load .env file first
load_dotenv()

# Now from_env() picks up values from .env
async with AionVision.from_env() as client:
    result = await client.upload_one("photo.jpg")
    print(result.description)

Custom .env Path

Specify a custom path to your .env file

from pathlib import Path
from aion import load_dotenv, AionVision

# Load from a specific path (string or Path)
load_dotenv("/path/to/config/.env")
load_dotenv(Path("config") / ".env")

# Override existing values (useful for testing)
load_dotenv(".env.test", override=True)

async with AionVision.from_env() as client:
    result = await client.upload_one("photo.jpg")

Security Warning

Never commit .env files containing API keys to version control. Add .env to your .gitignore file.

Priority Order

When resolving configuration values, the SDK uses this priority

Explicit parameters passed to from_env()
Environment variables (from OS or .env file)
Default values defined in the SDK

# AIONVISION_TIMEOUT=120.0 is set in environment

# This uses timeout=60.0 (explicit parameter wins)
async with AionVision.from_env(timeout=60.0) as client:
    ...

# This uses timeout=120.0 (from environment)
async with AionVision.from_env() as client:
    ...

Accessing Constants in Code

Environment variable names are exported as constants

from aion import (
    ENV_API_KEY,
    ENV_BASE_URL,
    ENV_TIMEOUT,
    ENV_MAX_RETRIES,
    ENV_RETRY_DELAY,
    ENV_POLLING_INTERVAL,
    ENV_POLLING_TIMEOUT,
    ENV_TENANT_ID,
    ENV_PROXY_URL,
    ENV_ENABLE_TRACING,
)

import os

# Check if API key is configured
if not os.environ.get(ENV_API_KEY):
    print(f"Please set {ENV_API_KEY} environment variable")

What's Next?

Client Configuration

All configuration options and patterns

Error Handling

Handle configuration and connection errors

SDK Tutorial

Learn the core SDK workflows