Official Python SDK

inertialai-python is the recommended way for Python developers to use InertialAI.

It gives you typed request and response models, native multi-modal inputs, sync and async clients, automatic retries for transient failures, and InertialAI-specific exceptions.

Beta release

inertialai-python is currently 0.1.0. It is stable enough for production use, but the API may still change before 1.0. Pin the version you deploy.

Installation

pip install inertialai-python

Requirements:

• Python 3.11 or newer
• An InertialAI API key from the dashboard

Authentication

Expose your API key as an environment variable:

export INERTIALAI_API_KEY="iai_..."

The SDK reads INERTIALAI_API_KEY automatically. You can also pass api_key="..." explicitly when creating the client.

Quickstart

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(
                time_series=[
                    [0.01, 0.02, 0.04, 0.03, 0.02],
                    [0.00, 0.01, 0.01, 0.02, 0.01],
                ],
                text="walking, 50 Hz accelerometer",
            )
        ],
    )

vector = response.data[0].embedding
print(f"Got a {len(vector)}-dim embedding using {response.model}")

Common input patterns

The SDK uses EmbeddingMultiModalInput for every item in input. Each item must include at least one of text or time_series.

Text-only

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[
            EmbeddingMultiModalInput(
                text="Standing jump trial performed during basketball practice."
            )
        ],
    )

Time-series only

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[
            EmbeddingMultiModalInput(
                time_series=[
                    [0.1, 0.2, 0.3, 0.4, 0.5],
                    [0.6, 0.7, 0.8, 0.9, 1.0],
                ]
            )
        ],
    )

Multi-modal

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[
            EmbeddingMultiModalInput(
                time_series=[
                    [72, 73, 71, 74, 72, 73],
                    [98.2, 98.3, 98.4, 98.3, 98.2, 98.3],
                ],
                text="Post-exercise recovery monitoring for a wearable health study.",
            )
        ],
    )

Batch requests

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[
            EmbeddingMultiModalInput(
                time_series=[[0.1, 0.2, 0.3]],
                text="Sensor reading from device A",
            ),
            EmbeddingMultiModalInput(
                time_series=[[0.5, 0.6, 0.7]],
                text="Sensor reading from device B",
            ),
            EmbeddingMultiModalInput(text="Maintenance note without sensor data"),
        ],
    )

for item in response.data:
    print(item.index, len(item.embedding))

Working with the response

client.embeddings.create() returns an EmbeddingResponse object with:

• model: the model used for the request
• data: a list of EmbeddingData objects
• usage: token accounting for the request
• create_time: the server timestamp

Example:

embedding = response.data[0]

print(response.model)
print(embedding.index)
print(len(embedding.embedding))
print(response.usage.total_tokens)
print(response.create_time.isoformat())

Which Python path should you choose?

Option	Best for	Tradeoffs
inertialai-python	New Python applications and most production integrations	Recommended; best ergonomics and type safety
OpenAI Python SDK	Existing codebases already standardized on openai	Requires json.dumps() for multi-modal payloads and does not expose InertialAI-native types
Raw HTTP	Non-Python clients, low-level debugging, or custom transport layers	You must build payloads, retries, and error handling yourself

Next steps

• Build your first working request: Making Your First API Request
• Learn async, timeouts, retries, and errors: Async, Configuration, and Errors
• See endpoint-specific examples: Using the Embeddings Endpoint
• Review compatibility guidance: OpenAI Python SDK Compatibility