Skip to main content

Async, Configuration, and Errors

This guide covers the main advanced usage patterns in inertialai-python.

Async client​

Use AsyncInertialAI in asyncio applications:

import asyncio

from inertialai_python import AsyncInertialAI, EmbeddingModel
from inertialai_python.types import EmbeddingMultiModalInput

async def main() -> None:
    async with AsyncInertialAI() as client:
        response = await client.embeddings.create(
            model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
            input=[EmbeddingMultiModalInput(text="sensor reading from accelerometer")],
        )
        print(response.data[0].embedding[:8])

asyncio.run(main())

InertialAI and AsyncInertialAI expose the same constructor parameters and the same embeddings.create() interface.

Client configuration​

Both clients support the following constructor options:

ParameterDefaultNotes
api_keyINERTIALAI_API_KEYPass explicitly if you do not want to use an environment variable.
base_urlhttps://inertialai.comUse the root URL, not /api/v1. The SDK adds endpoint paths for you.
timeout60.0 secondsAccepts a float or an httpx.Timeout object.
max_retries2Retries transient failures automatically.
http_clientauto-createdSupply a custom httpx.Client or httpx.AsyncClient if needed.

Example:

import httpx

from inertialai_python import EmbeddingModel, InertialAI
from inertialai_python.types import EmbeddingMultiModalInput

timeout = httpx.Timeout(30.0, connect=5.0)

with InertialAI(
    api_key="iai_...",
    base_url="https://inertialai.com",
    timeout=timeout,
    max_retries=4,
) as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[EmbeddingMultiModalInput(text="configured client example")],
    )

If neither api_key nor INERTIALAI_API_KEY is set, the client raises InertialAIError during construction.

Per-request timeouts​

You can override the client default timeout on a single request:

from inertialai_python import EmbeddingModel, InertialAI
from inertialai_python.types import EmbeddingMultiModalInput

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[EmbeddingMultiModalInput(text="tight timeout example")],
        timeout=10.0,
    )

Base64 output​

When you prefer a compact encoded payload instead of float arrays, request base64:

from inertialai_python import EmbeddingEncodingFormat, EmbeddingModel, InertialAI
from inertialai_python.types import EmbeddingMultiModalInput

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[EmbeddingMultiModalInput(text="base64 output example")],
        encoding_format=EmbeddingEncodingFormat.BASE64,
    )

base64_embedding = response.data[0].embedding

Error handling​

All SDK exceptions derive from InertialAIError:

InertialAIError
├── APIError
│   └── APIStatusError
│       ├── AuthenticationError
│       ├── ValidationError
│       ├── RateLimitError
│       └── InternalServerError
└── APIConnectionError
    └── APITimeoutError

All of these exception classes are importable directly from inertialai_python.

from inertialai_python import (
    APIConnectionError,
    APITimeoutError,
    AuthenticationError,
    EmbeddingModel,
    InertialAI,
    InternalServerError,
    RateLimitError,
    ValidationError,
)
from inertialai_python.types import EmbeddingMultiModalInput

try:
    with InertialAI() as client:
        response = client.embeddings.create(
            model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
            input=[EmbeddingMultiModalInput(text="example request")],
        )
        print(response.data[0].embedding[:5])

except AuthenticationError:
    print("Check INERTIALAI_API_KEY or pass api_key explicitly.")
except ValidationError as error:
    print(f"Validation failed: {error.status_code} {error.body}")
except RateLimitError:
    print("You have been rate limited. Reduce request volume and retry.")
except APITimeoutError:
    print("The request timed out.")
except APIConnectionError:
    print("The client could not reach the API.")
except InternalServerError:
    print("The API returned a server-side error.")

Automatic retries​

The SDK automatically retries:

  • 429
  • 500
  • 502
  • 503
  • 504
  • network failures
  • request timeouts

Retries use exponential backoff with jitter and honor the Retry-After header when the API provides one.

Context managers and cleanup​

Use with InertialAI() or async with AsyncInertialAI() so HTTP connections are closed cleanly after use.

If you hold a client open across many calls, close it explicitly when you are done.

Next steps​