Python SDK

Integrate TimechoAI forecasting into your app quickly with the Python SDK.

Requirements

• Python version: >= 3.9

Install

pip install timecho-ai

If your API key used to work but suddenly fails, try upgrading the SDK with pip install --upgrade timecho-ai and retry. If the issue persists, feel free to contact us for further investigation.

Request parameters

Supported model_id values: Auto · Timer-3.5 · Timer-3.0 · Chronos-2 · AutoARIMA · Holt-Winters

Parameter	Type	Required	Description	Constraints
targets	pd.DataFrame	Yes	Target time-series data	Length in [16, 2880]. Time column is optional.
model_id	str	No	Model ID	—
history_covs	pd.DataFrame	No	Historical covariates	Length equals the target length.
future_covs	pd.DataFrame	No	Covariates (including future data)	Length equals output_length. Numeric values only.
output_length	int	No	Forecast horizon	Range [1, 720]. Timer-3.5 defaults to 272; all other models default to 96.
output_start_time	Timestamp | datetime	No	Forecast start time	Must be later than the latest historical timestamp.
output_interval	datetime.timedelta	No	Time interval	—
time_col	str	No	Time column name	If set, all inputs must include a time column.
auto_adapt	bool	No	Auto data adaptation	Default True

Univariate forecasting

Sample CSV: sample.csv

import pandas as pd
from timecho_ai import TimechoAIClient

# Load sample data
raw_df = pd.read_csv("https://ai.timecho.com/data/sample.csv")
print(raw_df.head())

# Task: use 16 points to forecast the next 8 points
INPUT_LENGTH = 16
OUTPUT_LENGTH = 8

# Create a client (replace with your API key)
client = TimechoAIClient(api_key="your_timecho-ai_api_key")

# Build target DataFrame
target = raw_df[["time", "target"]][:INPUT_LENGTH]

# Forecast the next 8 points for "target"
result = client.forecast(
    targets=target,
    output_length=OUTPUT_LENGTH
)

print(result[0])

Forecasting with covariates

Sample CSV: sample_cov.csv

import pandas as pd
from timecho_ai import TimechoAIClient

# Create client
client = TimechoAIClient(api_key="your_timecho-ai_api_key")

# Task definition
INPUT_LENGTH = 16
OUTPUT_LENGTH = 8

# Load data
raw_df = pd.read_csv("https://ai.timecho.com/data/sample_cov.csv")

# Build target DataFrame
target = raw_df[["time", "target"]][:INPUT_LENGTH]

# Build historical covariates DataFrame
history_covs = raw_df[["time", "temperature", "humidity"]][:INPUT_LENGTH]

# Forecast with covariates
result = client.forecast(
    targets=target,
    history_covs=history_covs,
    output_length=OUTPUT_LENGTH,
    time_col="time",
    auto_adapt=True
)

print(result[0])

Error handling

The SDK converts HTTP errors from the service into specific exception types, so your application can handle authentication issues, invalid parameters, rate limits, and temporary service failures separately. Network connection failures, request timeouts, and client-side validation errors are also reported as dedicated exceptions.

Exception	When it is raised
BadRequestError	HTTP 400 — malformed request / invalid parameters
AuthenticationError	HTTP 401 — missing or invalid credentials
PermissionDeniedError	HTTP 403 — credentials are valid, but the operation is forbidden
NotFoundError	HTTP 404 — referenced resource (model / file) does not exist
ConflictError	HTTP 409 — resource state conflict, such as already existing or not loaded
UnprocessableEntityError	HTTP 422 — semantic validation failed, such as output_length out of range or target variable count not equal to 1
RateLimitError	HTTP 429 — rate limit exceeded
InternalServerError	HTTP 500 — unhandled server-side error
ServiceUnavailableError	HTTP 503 — service temporarily unavailable, usually retryable
APIError	Base class for the HTTP exceptions above. It includes status_code and response_body. Unlisted 4xx errors raise APIError; unlisted 5xx errors raise ServerError
ConnectionError	Transport layer: connection failed
TimeoutError	Transport layer: request timed out
ValidationError	Client-side input validation failed before the request was sent

Next steps

Explore more TimechoAI capabilities:

• REST API →
• Quickstart →