POST /v1/forecast
POST https://api.sequenxai.com/v1/forecast 对一个或多个实体的历史序列做在线预测。服务端先按生效的清洗策略清洗数据(raw 预设则只做结构校验),再调用所选模型,最后把预测结果还原到时间戳上返回。认证方式见认证与请求头。
1. 请求示例
export SEQUENX_API_KEY="sqx_live_..." # created at https://platform.sequenxai.com
# 96 points at 15-minute steps, h=24, level=[80, 90], model hora-1.0
curl -sSO https://docs.sequenxai.com/data/power-grid-15m.json
curl -sS -X POST "https://api.sequenxai.com/v1/forecast" \
-H "Authorization: Bearer $SEQUENX_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Request-Id: quickstart-0001" \
-d @power-grid-15m.jsonimport math
import os
import requests
API_URL = "https://api.sequenxai.com/v1/forecast"
API_KEY = os.environ["SEQUENX_API_KEY"]
# 48 hourly observations of one meter.
series = [
{
"unique_id": "meter-001",
"ds": f"2026-09-{1 + i // 24:02d}T{i % 24:02d}:00:00Z",
"y": round(140 + 8 * math.sin(2 * math.pi * i / 24), 1),
}
for i in range(48)
]
resp = requests.post(
API_URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json={"model": "hora-1.0", "series": series, "h": 24, "freq": "1h", "level": [80, 90]},
timeout=180,
)
body = resp.json()
if resp.status_code != 200:
error = body["error"]
raise SystemExit(f"{resp.status_code} {error['code']}: {error['message']} ({error['request_id']})")
print(body["request_id"], body["effective_policy"]["id"], body["usage"])
for row in body["forecast"][:3]:
print(row["ds"], row["y_hat"], row["intervals"]["80"])// Node.js 18+ (global fetch). Call from your server; never ship the key to a browser.
const API_URL = "https://api.sequenxai.com/v1/forecast";
// 48 hourly observations of one meter.
const series = Array.from({ length: 48 }, (_, i) => ({
unique_id: "meter-001",
ds: new Date(Date.UTC(2026, 8, 1, i)).toISOString().replace(".000Z", "Z"),
y: Math.round((140 + 8 * Math.sin((2 * Math.PI * i) / 24)) * 10) / 10,
}));
const resp = await fetch(API_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SEQUENX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ model: "hora-1.0", series, h: 24, freq: "1h", level: [80, 90] }),
signal: AbortSignal.timeout(180_000),
});
const body = await resp.json();
if (!resp.ok) {
const { code, message, request_id } = body.error;
throw new Error(`${resp.status} ${code}: ${message} (${request_id})`);
}
console.log(body.request_id, body.effective_policy.id, body.usage);
for (const row of body.forecast.slice(0, 3)) {
console.log(row.ds, row.y_hat, row.intervals["80"]);
}2. 请求体字段
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model | string | 否 | hora-1.0 | hora-1.0 或其别名 hora;其他任何 id 返回 422 MODEL_NOT_AVAILABLE。上限见模型与能力上限。 |
model_options | object | 否 | — | 模型开关 nonnegative("auto" / true / false,默认 "auto")与 flip_average(默认 true)。封闭对象:未知的键返回 422 VALIDATION_ERROR,模型不支持的键返回 422 MODEL_OPTION_UNSUPPORTED。计费仍按预测点。见模型选项。 |
series | array | 是 | — | 历史长表记录,至少 1 行;与 future_covariates 合计单次最多 200,000 行(超出返回 POINTS_EXCEEDED)。每个实体不能长于模型的最大上下文(SERIES_TOO_LONG),请只发送最近的点。 |
series[].unique_id | string | 是 | — | 实体标识;同一请求可包含多个实体。 |
series[].ds | string | 是 | — | 时间戳。带偏移(Z、+08:00)时按偏移读取,不带偏移时按 options.timezone 读取,见长表、频率与时区。 |
series[].y | number 或 null | 是 | — | 观测值;null 表示缺失。字段本身必须出现,非有限数被拒绝。 |
series[] 的其他列 | 数字 / 字符串 / 布尔 / null | 否 | — | 历史协变量,最多 8 列;对齐到清洗后的序列,并在 model_input[].covariates 中逐列报告。模型目前不使用协变量,通过数据检查的列报告 model_unsupported。见协变量支持现状。 |
h | integer | 是 | — | 预测步数,1–2048,且不能超过模型的最大步长,否则返回 422 HORIZON_EXCEEDS_MODEL。 |
freq | string | 否 | 推断 | 频率字符串,见频率字符串。省略时由清洗服务推断;raw 预设下必填。 |
level | integer[] | 否 | 无 | 区间水平,每个取 1–99,重复值会被合并。省略时响应不含 intervals。模型不能原生输出的分位数见预测区间。 |
quantile_policy | nearest / strict | 否 | nearest | Beta。nearest 用最接近的原生分位点代替并按实际水平标注区间;strict 遇到非原生分位数时返回 422 QUANTILE_UNSUPPORTED。同样作用于 point_quantile。 |
point_quantile | number | 否 | 无(中位数) | Beta。用该分位数作为 y_hat(如 0.7 即 P70)。取值 0.01–0.99,最多 3 位小数,否则返回 422 VALIDATION_ERROR。按 quantile_policy 映射到模型原生分位点,见预测区间第 5 节。 |
clean_series | boolean | 否 | true | false 时只检测不修复:一旦需要修复,返回 422 TIMESTAMP_IRREGULAR 或 SERIES_DISCONTINUOUS。 |
clean_exog | boolean | 否 | true | 线性填补协变量的短缺口(不超过策略的短缺口上限);为 false 时任何缺口都会使该列不可用。 |
future_covariates | array | 否 | — | 预测窗口内已知的值,每个 unique_id 与预测时间点一行。列必须同时出现在 series 行上(否则 422 COVARIATE_COLUMN_MISMATCH);不得包含 y(422 FUTURE_COVARIATES_INVALID)。 |
options.timezone | string | 否 | UTC | IANA 时区名(如 Asia/Shanghai),用于读取不带偏移的 ds;无效名称返回 422 VALIDATION_ERROR。 |
options.ds_format | dmy 或 mdy | 否 | — | D/M/YYYY 类时间戳无法从数据判断日月顺序时使用,否则返回 AMBIGUOUS_DATE_FORMAT。 |
options.gap_split_min_steps | integer ≥ 0 | 否 | 自动 | 缺口超过多少个网格步长时只保留最近的连续段;0 关闭切分。 |
options.cleaning.preset | default / strict / raw | 否 | 见下 | 清洗预设。省略时依次取密钥默认、组织默认、平台默认(default)。 |
options.cleaning.version | 2026-13(2026-10 / 2026-11 / 2026-12 已弃用) | 否 | 2026-13 | 规则集版本,解析顺序与预设相同。建议不传;2026-10、2026-11 与 2026-12 将在公告后移除,显式指定时响应带 cleaning_version_deprecated 提醒,见策略版本。 |
options.cleaning.impute_method、seasonal_period、nonnegative、bounds、structural_zero、business_days、long_gap | 见链接 | 否 | — | 2026-11 及之后版本的调节项(默认的 2026-13 同样支持);在已弃用的 2026-10 下返回 422 CLEANING_OPTION_UNSUPPORTED(带 details.requires_version)。见清洗策略版本参考。 |
options.cleaning.accept | string[] | 否 | — | 按决定 id 采纳被提议的决定;最多 200 个,每个不超过 200 字符。 |
options.cleaning.decline | string[] | 否 | — | 按决定 id 撤回已应用的可撤回决定;限制同上。 |
options.router_strategy | auto / ensemble / single / fast | 否 | — | 契约预留字段,接受并校验取值,当前无效果。 |
请求体顶层或 options.cleaning 内出现契约之外的字段会返回 422 VALIDATION_ERROR(details.errors[].field 指出字段,如 options.cleaning.imputer),不会被静默忽略;options 顶层未列出的键仍会被忽略。预设、accept 与 decline 的用法见清洗策略与清洗报告。
3. 校验顺序
服务端按以下顺序处理请求,前面的检查失败时不会进入后面的步骤。所有非 200 响应都不计费。
- 认证与权限范围:401
INVALID_API_KEY、403INSUFFICIENT_SCOPE。随后检查账号状态:SequenxAI 临时暂停该接口时返回 503SERVICE_UNAVAILABLE(带Retry-After),以及 403ACCOUNT_SUSPENDED、403ORG_PENDING_DELETION。再检查Idempotency-Key(传了才检查):键不合规返回 400VALIDATION_ERROR,另有 422IDEMPOTENCY_KEY_REUSED、409IDEMPOTENCY_IN_PROGRESS;对已完成请求的同键同体重试在这一步直接返回保存的结果,不计入每分钟请求数。 - 账号每分钟请求数(账号下所有密钥共用):429,
X-RateLimit-Policy: forecast-rpm。被限流的请求不记录。 - 请求体解析与字段校验:400
MALFORMED_JSON、422VALIDATION_ERROR(含协变量列超过 8 列)、FUTURE_COVARIATES_INVALID、COVARIATE_COLUMN_MISMATCH。 - 单次行数上限(
series与future_covariates合计):422POINTS_EXCEEDED。 - 清洗预设解析:422
CLEANING_OPTION_UNSUPPORTED;raw缺少freq时返回 422VALIDATION_ERROR。 - 模型:
hora-1.0/hora以外的 id 返回 422MODEL_NOT_AVAILABLE,model_options中模型不支持的键返回 422MODEL_OPTION_UNSUPPORTED,暂不可用返回 503SERVICE_UNAVAILABLE;h超过模型上限返回 422HORIZON_EXCEEDS_MODEL;quantile_policy: strict下请求了非原生分位数(含point_quantile)返回 422QUANTILE_UNSUPPORTED;某个实体不重复的时间戳数(raw预设下为行数)超过模型最大上下文时返回 422SERIES_TOO_LONG。 - 每日点数额度:按「行数 +
h× 实体数」预占,额度不足返回 429,X-RateLimit-Policy: forecast-daily-points。 - 清洗(或
raw结构校验):各类 422 清洗错误码、RAW_INPUT_INVALID、SERIES_TOO_SHORT;清洗后的规则网格(含补齐的点)长于模型最大上下文时返回SERIES_TOO_LONG。 - 模型推理:503
MODEL_BUSY、504GATEWAY_TIMEOUT、503SERVICE_UNAVAILABLE。 - 成功:按模型实际收到的观测点与预测点结算,预占的剩余额度退回。
4. 响应字段
| 字段 | 说明 |
|---|---|
request_id | 服务端请求 ID,与响应头 X-Request-Id 相同。 |
model_used | 实际运行的模型 ID:hora-1.0,请求使用别名 hora 时也是如此。 |
freq | 传入 freq 时原样返回;省略时返回推断出的规范写法(如 h、15min、MS)。 |
point_quantile | Beta。仅在请求传了 point_quantile 时出现:实际用作 y_hat 的原生分位数(被替换时与请求值不同)。 |
forecast[] | 每个实体 h 行:unique_id、ds(UTC,YYYY-MM-DDTHH:MM:SSZ)、y_hat,以及请求了 level 时的 intervals。y_hat 默认是模型的中位数(0.5 分位),不是期望值;传了 point_quantile 时是该分位数。 |
forecast[].intervals | 以实际使用的分位数对应的水平字符串为键("80"、"90"),值为 {"lo", "hi"},保证 lo ≤ hi。见预测区间。 |
quantile_report | Beta。{policy, requested, used, substitutions[]}:请求的分位数、实际使用的原生分位数,以及每一处替换 {requested, used}。传了 point_quantile 时另有 point_forecast: {requested, used, method}。 |
data_quality | 兼容旧版的质量摘要:status(ok 或 cleaned)、inferred_freq(仅在省略 freq 时有值)、missing_ratio(修复前的时间戳缺口占比)、imputed_points、outlier_points_suppressed(当前恒为 0,异常值只标记不修改)、timezone_normalized、notes。 |
usage.series_count | 处理的实体数。 |
usage.input_data_points | 实际喂给模型的观测点数:在长缺口切分之后统计,不含插值点与补入的时间戳。 |
usage.forecast_data_points | 生成的预测点数(h × 实体数)。 |
usage.latency_ms | 服务端从收到请求到预测结果组装完成的耗时;不是 SLA。 |
effective_policy | {id, preset, version, source}:生效的清洗预设、版本及来源(request / key / org / platform)。 |
model_input[] | 每个实体:context_points(交给模型的点数)、fed_points(其中的观测点数)、truncated(恒为 0:长于模型上下文的序列会被拒绝,不会被截断)、missing_mode、covariates_used,发送了协变量时还有 covariates[](逐列:name、role、used、reason)。以下字段仅在适用时出现:masked_tail 与 tail_handling(策略版本 2026-12 起保留的末尾空值),以及 long_gap_points、long_gap_handling 与 long_gap_reason(options.cleaning.long_gap: "mask" 时;SequenxAI Omni 把长缺口读作缺失值,long_gap_handling 为 "mask",见长缺口:填补还是屏蔽)。 |
warnings[] | Beta。没有阻止预测的提醒;没有提醒时省略。code 为 trailing_values_missing、long_gap_mask_unavailable 或 cleaning_version_deprecated,涉及单个实体时带 unique_id。今后可能新增取值;使用预测前请先查看。 |
cleaning_report | cleaning_report/1 结构化清洗报告(Beta);raw 预设下不返回。见清洗策略与清洗报告。 |
5. 响应示例
数值仅为示意,cleaning_report 已折叠:
{
"request_id": "req_4f1c8e2a9b7d4e0c8a3f5b6d7e8f9a0b",
"model_used": "hora-1.0",
"freq": "1h",
"forecast": [
{
"unique_id": "meter-001",
"ds": "2026-09-03T00:00:00Z",
"y_hat": 140.6,
"intervals": {
"80": {"lo": 137.9, "hi": 143.2},
"90": {"lo": 136.4, "hi": 144.8}
}
}
],
"data_quality": {
"status": "ok",
"inferred_freq": null,
"missing_ratio": 0.0,
"imputed_points": 0,
"outlier_points_suppressed": 0,
"timezone_normalized": true,
"notes": []
},
"usage": {
"series_count": 1,
"input_data_points": 48,
"forecast_data_points": 24,
"latency_ms": 812
},
"effective_policy": {
"id": "default@2026-13",
"preset": "default",
"version": "2026-13",
"source": "platform"
},
"model_input": [
{
"unique_id": "meter-001",
"context_points": 48,
"fed_points": 48,
"truncated": 0,
"missing_mode": "filled",
"covariates_used": false
}
],
"quantile_report": {
"policy": "nearest",
"requested": [0.05, 0.1, 0.5, 0.9, 0.95],
"used": [0.05, 0.1, 0.5, 0.9, 0.95],
"substitutions": []
},
"cleaning_report": {
"schema_version": "cleaning_report/1",
"policy": {"id": "default@2026-13", "...": "..."},
"overall": {"series_count": 1, "input_points": 48, "output_points": 48, "...": "..."},
"series": ["..."],
"warnings": [],
"blocking": [],
"decisions": []
}
}6. raw 预设
options.cleaning.preset: "raw" 跳过清洗,数据原样交给模型前的结构校验。适合已经在自己系统里清洗好的数据。要求:
freq必填,且必须是固定步长(s、min、h、D、W及其倍数);MS、M@15等日历频率不支持。- 每个
ds严格为YYYY-MM-DDTHH:MM[:SS[.ffffff]],并以Z或±HH:MM结尾;不接受其他格式。 - 每个实体的行按时间严格递增,相邻步长恰好等于
freq;不会排序、去重或补点。 - 每个
y都是有限数值,不能为null。 - 不能与
accept/decline或impute_method等清洗参数同时使用(422CLEANING_OPTION_UNSUPPORTED)。
不满足时返回 422 RAW_INPUT_INVALID,details.violations 最多列出 20 条问题,每条含 unique_id、index 与 reason,reason 取值为 freq_invalid、calendar_freq_unsupported、ds_format、ds_duplicate、ds_not_increasing、step_mismatch、not_observed:
{
"error": {
"code": "RAW_INPUT_INVALID",
"message": "Raw input is not a regular, finite series",
"request_id": "req_…",
"details": {
"violations": [
{"unique_id": "meter-001", "index": 5, "reason": "step_mismatch"}
],
"hint": "Use the default cleaning preset, or call /v1/clean to see the cleaning report."
}
}
}raw 路径的响应没有 cleaning_report,data_quality 固定为 {"status": "ok", "missing_ratio": 0.0}。raw 路径在运行前就按每个实体的行数检查模型最大上下文(SERIES_TOO_LONG),不做任何截断。