Using the Embeddings Endpoint
The POST /api/v1/embeddings endpoint generates vector embeddings from time-series data using InertialAI's foundation models. These embeddings transform sensor and time-series data into dense vector representations that capture semantic meaning, enabling similarity search, clustering, classification, and other AI-driven tasks.
Request Structure
Required Parameters
input: Your embedding data. Accepts an array of multi-modal input objects that can contain:- Time-series only:
[{"time_series": [[channel_1_values], [channel_2_values]]}, ...] - Text only:
[{"text": "Your text description"}, ...] - Multi-modal (time-series + text):
[{"time_series": [[values]], "text": "Context description"}, ...] - Can also be provided as a JSON string representation of the same structure
- Time-series only:
model: The model ID to use (e.g.,"inertial-embed-alpha")
Optional Parameters
dimensions: Number of dimensions for output embeddings (e.g.,24). Reduces or expands the default embedding size for your use case.encoding_format: Return format for embeddings. Options:"float"(default): Array of floating-point numbers"base64": Base64-encoded string for efficient transmission
Common Use Cases
1. Single Time-Series Sample
Generate an embedding for a single multi-channel time-series recording:
import requests
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[0.1, 0.2, 0.3, 0.4, 0.5], # Channel 1
[0.6, 0.7, 0.8, 0.9, 1.0] # Channel 2
]
}
],
"model": "inertial-embed-alpha"
}
)
embedding = response.json()["data"][0]["embedding"]
Business Context: Analyze a single sensor reading (e.g., accelerometer data from a manufacturing machine) to detect anomalies or classify operational states.
2. Text-Only Input
Generate embeddings from text descriptions without time-series data:
import requests
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"text": "Standing jump trial performed by athlete during training session."
}
],
"model": "inertial-embed-alpha"
}
)
embedding = response.json()["data"][0]["embedding"]
Business Context: Generate embeddings for textual sensor annotations, activity labels, medical notes, or equipment descriptions to enable semantic search and contextual analysis.
3. Multi-Modal: Time-Series with Text Context
Combine time-series data with descriptive text for richer semantic embeddings:
import requests
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[72, 73, 71, 74, 72, 73], # Heart rate (BPM)
[98.2, 98.3, 98.4, 98.3, 98.2, 98.3] # Body temp (°F)
],
"text": "Post-exercise recovery monitoring, patient ID 12345, age 32, male"
}
],
"model": "inertial-embed-alpha"
}
)
embedding = response.json()["data"][0]["embedding"]
Business Context: Enrich sensor data with contextual information such as patient demographics, device locations, experimental conditions, or operational states. The text provides semantic context that helps the model better understand the meaning and significance of the numerical data.
4. Batch Processing
Process multiple time-series samples in a single request for efficiency:
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
"text": "Sensor reading from device A"
},
{
"time_series": [[0.7, 0.8, 0.9], [0.1, 0.11, 0.12]],
"text": "Sensor reading from device B"
},
{
"text": "Equipment inspection notes - no sensor data available"
}
],
"model": "inertial-embed-alpha"
}
)
embeddings = [item["embedding"] for item in response.json()["data"]]
Business Context: Process hourly sensor readings from multiple devices, batch daily financial time-series data, or analyze patient vitals across multiple recording sessions. Mix time-series data with text-only records when some samples lack sensor data.
5. Dimensionality Reduction
Specify custom embedding dimensions to balance accuracy and storage/compute costs:
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [{"time_series": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]}],
"model": "inertial-embed-alpha",
"dimensions": 24
}
)
Business Context: Reduce embedding size for mobile applications, edge devices with limited memory, or large-scale vector databases where storage costs matter.
6. Base64 Encoding
Use base64 encoding for more efficient data transmission:
import base64
import numpy as np
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [{"time_series": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]}],
"model": "inertial-embed-alpha",
"encoding_format": "base64"
}
)
# Decode base64 embedding
base64_embedding = response.json()["data"][0]["embedding"]
embedding_bytes = base64.b64decode(base64_embedding)
embedding = np.frombuffer(embedding_bytes, dtype=np.float32)
Business Context: Optimize bandwidth when transmitting embeddings over networks with limited capacity or when integrating with systems that prefer binary data formats.
7. String Input
Pass multi-modal data as a JSON string:
import json
embedding_data = [
{
"time_series": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
"text": "Accelerometer data from device A"
},
{
"time_series": [[0.7, 0.8, 0.9], [0.10, 0.11, 0.12]],
"text": "Accelerometer data from device B"
}
]
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": json.dumps(embedding_data),
"model": "inertial-embed-alpha"
}
)
Business Context: Useful when working with systems that serialize data as strings or when time-series data is stored in text-based formats.
Note: When using the OpenAI Python SDK, you must always stringify your input using json.dumps() because the SDK's embeddings.create() method only accepts string inputs. This format is required for multi-modal inputs combining time-series and text data. Refer to Using the OpenAI Python SDK for more details.
Real-World Multi-Modal Examples
IoT Sensor Data with Context
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[23.5, 23.7, 23.9, 24.1, 24.0], # Temperature (°C)
[45.2, 45.5, 45.8, 46.1, 45.9], # Humidity (%)
[1013, 1014, 1013, 1012, 1013] # Pressure (hPa)
],
"text": "Indoor climate sensor - Conference room A, normal operation"
}
],
"model": "inertial-embed-alpha"
}
)
Financial Time-Series with Market Context
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[150.2, 151.3, 150.8, 152.1, 151.9], # Price
[1250000, 1380000, 1120000, 1450000, 1290000] # Volume
],
"text": "AAPL daily data, tech sector rally, pre-earnings announcement"
}
],
"model": "inertial-embed-alpha"
}
)
Manufacturing Equipment with Operational Context
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[2100, 2150, 2180, 2140, 2120], # RPM
[65, 66, 68, 67, 66], # Temperature (°C)
[8.2, 8.5, 8.7, 8.4, 8.3] # Vibration (mm/s)
],
"text": "CNC machine #42, production shift 2, cutting aluminum parts"
}
],
"model": "inertial-embed-alpha"
}
)
Sports Analytics with Activity Context
response = requests.post(
"https://api.inertialai.com/api/v1/embeddings",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"input": [
{
"time_series": [
[34.61, 35.11, 35.21, 35.36, 35.25], # Vertical acceleration
[2.1, 2.3, 2.5, 2.4, 2.2] # Horizontal velocity
],
"text": "Standing vertical jump trial, athlete ID 789, elite basketball player"
}
],
"model": "inertial-embed-alpha"
}
)
Response Structure
Successful responses return a JSON object with:
object: Always"list"model: Model ID useddata: Array of embedding objects, each containing:object: Always"embedding"index: Position in the input batchembedding: Vector representation (array of floats or base64 string)
usage: Token usage informationprompt_tokens: Input tokens consumedtotal_tokens: Total tokens consumed
create_time: ISO 8601 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"
}
Business Applications
Anomaly Detection
Generate embeddings for normal operational data, then compare new readings to detect deviations. Useful for predictive maintenance, fraud detection, or quality control.
# Train: Create embeddings for normal operation
normal_embeddings = []
for reading in normal_sensor_data:
response = requests.post(url, headers=headers, json={
"input": [{"time_series": reading}],
"model": "inertial-embed-alpha"
})
normal_embeddings.append(response.json()["data"][0]["embedding"])
# Inference: Check if new reading is anomalous
new_response = requests.post(url, headers=headers, json={
"input": [{"time_series": new_reading}],
"model": "inertial-embed-alpha"
})
new_embedding = new_response.json()["data"][0]["embedding"]
# Compare similarity with normal_embeddings
# Flag as anomaly if distance exceeds threshold
Similarity Search
Find similar time-series patterns across your dataset. Applications include finding similar patient cases, matching financial market conditions, or identifying recurring equipment behaviors.
Time-Series Classification
Use embeddings as features for ML classifiers to categorize sensor data, classify user activities from wearable devices, or segment financial instruments by behavior.
Clustering and Segmentation
Group similar time-series data to discover operational patterns, segment customers by behavior, or organize sensor networks by activity types.
Error Handling
The endpoint returns validation errors (HTTP 422) when input doesn't match the expected schema:
try:
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
embeddings = response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 422:
print("Validation error:", e.response.json()["detail"])
elif e.response.status_code == 401:
print("Authentication failed - check your API key")
else:
print(f"Request failed: {e}")
Tip: The OpenAI Python SDK provides more sophisticated error handling with specific exception types (AuthenticationError, APIError, RateLimitError, etc.) and automatic retry logic for transient failures.
Next Steps
- Use the OpenAI Python SDK: Using the OpenAI Python SDK
- Review the API Reference for detailed schema information