Skip to main content

Using the Embeddings Endpoint

The POST /api/v1/embeddings endpoint generates vector embeddings from text, time-series data, or both together using inertial-embed-alpha.

For Python applications, the recommended way to call this endpoint is the official inertialai-python client. This page focuses on the endpoint shape and the most common embeddings-specific options.

Request Structure​

Each request needs:

  • input: an array of embedding inputs. Each item may contain time_series, text, or both together.
  • model: the model identifier. Today this is inertial-embed-alpha.

Optional fields:

FieldTypeDescription
dimensionsintRequest a custom embedding size when your storage or retrieval system needs a different vector length.
encoding_format"float" or "base64"Return standard float arrays or base64-encoded vectors.

Input shape​

Each input object supports the following fields:

FieldTypeDescription
time_serieslist[list[float]]Multi-channel signal data. Outer list = channels, inner list = samples in time order.
textstrNatural-language context to embed alongside, or instead of, the signal.

At least one of time_series or text must be present for each item.

All examples below use the official SDK:

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

Text-only input​

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

embedding = response.data[0].embedding

Time-series-only input​

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 input​

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 processing​

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"),
        ],
    )

embeddings = [item.embedding for item in response.data]

Custom dimensions and base64 output​

with InertialAI() as client:
    response = client.embeddings.create(
        model=EmbeddingModel.INERTIAL_EMBED_ALPHA,
        input=[EmbeddingMultiModalInput(text="compress this embedding")],
        dimensions=256,
        encoding_format=EmbeddingEncodingFormat.BASE64,
    )

base64_embedding = response.data[0].embedding

Raw HTTP equivalent​

If you are debugging requests, using another language, or validating payloads outside the SDK, the equivalent raw HTTP call looks like this:

curl -sS \
  -X POST "https://inertialai.com/api/v1/embeddings" \
  -H "Authorization: Bearer ${INERTIALAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inertial-embed-alpha",
    "input": [
      {
        "time_series": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
        "text": "Accelerometer capture from device A"
      }
    ]
  }'

If you are using the OpenAI client instead of inertialai-python, you must still serialize multi-modal inputs with json.dumps(). See OpenAI Python SDK Compatibility.

Response Structure​

Successful responses contain:

  • object: "list"
  • model: the model used for the request
  • data: one embedding result per input item
  • usage: token accounting for the request
  • create_time: request timestamp

Example response:

{
  "object": "list",
  "model": "inertial-embed-alpha",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.023, -0.015, 0.042, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 15
  },
  "create_time": "2026-01-23T10:30:00.000000Z"
}

Common use cases​

  • Similarity search across sensor captures, logs, notes, or mixed multi-modal datasets
  • Anomaly detection by comparing new embeddings against a baseline of normal behavior
  • Classification by feeding embeddings into downstream ML models
  • Clustering and segmentation to discover natural groups in equipment, patient, or market data

Error Handling​

With the official SDK, error handling uses InertialAI-specific exceptions such as AuthenticationError, ValidationError, RateLimitError, APIConnectionError, and APITimeoutError. See Async, Configuration, and Errors for examples.

If you send raw HTTP requests directly, check the response status code:

  • 401: authentication failed
  • 403: key is valid but does not have access
  • 422: request body does not match the schema
  • 429: rate limited

Next Steps​