开发者文档:/v1/forecast 与 /v1/clean 已开放,API 密钥在 SequenxAI 平台自助创建。

POST /v1/forecast

POST https://api.sequenxai.com/v1/forecast 对一个或多个实体的历史序列做在线预测。服务端先按生效的清洗策略清洗数据(raw 预设则只做结构校验),再调用所选模型,最后把预测结果还原到时间戳上返回。认证方式见认证与请求头。

1. 请求示例

forecast.sh
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.json

2. 请求体字段

字段类型必填默认说明
modelstring否hora-1.0hora-1.0 或其别名 hora;其他任何 id 返回 422 MODEL_NOT_AVAILABLE。上限见模型与能力上限。
model_optionsobject否—模型开关 nonnegative("auto" / true / false,默认 "auto")与 flip_average(默认 true)。封闭对象:未知的键返回 422 VALIDATION_ERROR,模型不支持的键返回 422 MODEL_OPTION_UNSUPPORTED。计费仍按预测点。见模型选项。
seriesarray是—历史长表记录,至少 1 行;与 future_covariates 合计单次最多 200,000 行(超出返回 POINTS_EXCEEDED)。每个实体不能长于模型的最大上下文(SERIES_TOO_LONG),请只发送最近的点。
series[].unique_idstring是—实体标识;同一请求可包含多个实体。
series[].dsstring是—时间戳。带偏移(Z、+08:00)时按偏移读取,不带偏移时按 options.timezone 读取,见长表、频率与时区。
series[].ynumber 或 null是—观测值;null 表示缺失。字段本身必须出现,非有限数被拒绝。
series[] 的其他列数字 / 字符串 / 布尔 / null否—历史协变量,最多 8 列;对齐到清洗后的序列,并在 model_input[].covariates 中逐列报告。模型目前不使用协变量,通过数据检查的列报告 model_unsupported。见协变量支持现状。
hinteger是—预测步数,1–2048,且不能超过模型的最大步长,否则返回 422 HORIZON_EXCEEDS_MODEL。
freqstring否推断频率字符串,见频率字符串。省略时由清洗服务推断;raw 预设下必填。
levelinteger[]否无区间水平,每个取 1–99,重复值会被合并。省略时响应不含 intervals。模型不能原生输出的分位数见预测区间。
quantile_policynearest / strict否nearestBeta。nearest 用最接近的原生分位点代替并按实际水平标注区间;strict 遇到非原生分位数时返回 422 QUANTILE_UNSUPPORTED。同样作用于 point_quantile。
point_quantilenumber否无(中位数)Beta。用该分位数作为 y_hat(如 0.7 即 P70)。取值 0.01–0.99,最多 3 位小数,否则返回 422 VALIDATION_ERROR。按 quantile_policy 映射到模型原生分位点,见预测区间第 5 节。
clean_seriesboolean否truefalse 时只检测不修复:一旦需要修复,返回 422 TIMESTAMP_IRREGULAR 或 SERIES_DISCONTINUOUS。
clean_exogboolean否true线性填补协变量的短缺口(不超过策略的短缺口上限);为 false 时任何缺口都会使该列不可用。
future_covariatesarray否—预测窗口内已知的值,每个 unique_id 与预测时间点一行。列必须同时出现在 series 行上(否则 422 COVARIATE_COLUMN_MISMATCH);不得包含 y(422 FUTURE_COVARIATES_INVALID)。
options.timezonestring否UTCIANA 时区名(如 Asia/Shanghai),用于读取不带偏移的 ds;无效名称返回 422 VALIDATION_ERROR。
options.ds_formatdmy 或 mdy否—D/M/YYYY 类时间戳无法从数据判断日月顺序时使用,否则返回 AMBIGUOUS_DATE_FORMAT。
options.gap_split_min_stepsinteger ≥ 0否自动缺口超过多少个网格步长时只保留最近的连续段;0 关闭切分。
options.cleaning.presetdefault / strict / raw否见下清洗预设。省略时依次取密钥默认、组织默认、平台默认(default)。
options.cleaning.version2026-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.acceptstring[]否—按决定 id 采纳被提议的决定;最多 200 个,每个不超过 200 字符。
options.cleaning.declinestring[]否—按决定 id 撤回已应用的可撤回决定;限制同上。
options.router_strategyauto / ensemble / single / fast否—契约预留字段,接受并校验取值,当前无效果。

请求体顶层或 options.cleaning 内出现契约之外的字段会返回 422 VALIDATION_ERROR(details.errors[].field 指出字段,如 options.cleaning.imputer),不会被静默忽略;options 顶层未列出的键仍会被忽略。预设、accept 与 decline 的用法见清洗策略与清洗报告。

3. 校验顺序

服务端按以下顺序处理请求,前面的检查失败时不会进入后面的步骤。所有非 200 响应都不计费。

  1. 认证与权限范围:401 INVALID_API_KEY、403 INSUFFICIENT_SCOPE。随后检查账号状态:SequenxAI 临时暂停该接口时返回 503 SERVICE_UNAVAILABLE(带 Retry-After),以及 403 ACCOUNT_SUSPENDED、403 ORG_PENDING_DELETION。再检查 Idempotency-Key(传了才检查):键不合规返回 400 VALIDATION_ERROR,另有 422 IDEMPOTENCY_KEY_REUSED、409 IDEMPOTENCY_IN_PROGRESS;对已完成请求的同键同体重试在这一步直接返回保存的结果,不计入每分钟请求数。
  2. 账号每分钟请求数(账号下所有密钥共用):429,X-RateLimit-Policy: forecast-rpm。被限流的请求不记录。
  3. 请求体解析与字段校验:400 MALFORMED_JSON、422 VALIDATION_ERROR(含协变量列超过 8 列)、FUTURE_COVARIATES_INVALID、COVARIATE_COLUMN_MISMATCH。
  4. 单次行数上限(series 与 future_covariates 合计):422 POINTS_EXCEEDED。
  5. 清洗预设解析:422 CLEANING_OPTION_UNSUPPORTED;raw 缺少 freq 时返回 422 VALIDATION_ERROR。
  6. 模型:hora-1.0 / hora 以外的 id 返回 422 MODEL_NOT_AVAILABLE,model_options 中模型不支持的键返回 422 MODEL_OPTION_UNSUPPORTED,暂不可用返回 503 SERVICE_UNAVAILABLE;h 超过模型上限返回 422 HORIZON_EXCEEDS_MODEL;quantile_policy: strict 下请求了非原生分位数(含 point_quantile)返回 422 QUANTILE_UNSUPPORTED;某个实体不重复的时间戳数(raw 预设下为行数)超过模型最大上下文时返回 422 SERIES_TOO_LONG。
  7. 每日点数额度:按「行数 + h × 实体数」预占,额度不足返回 429,X-RateLimit-Policy: forecast-daily-points。
  8. 清洗(或 raw 结构校验):各类 422 清洗错误码、RAW_INPUT_INVALID、SERIES_TOO_SHORT;清洗后的规则网格(含补齐的点)长于模型最大上下文时返回 SERIES_TOO_LONG。
  9. 模型推理:503 MODEL_BUSY、504 GATEWAY_TIMEOUT、503 SERVICE_UNAVAILABLE。
  10. 成功:按模型实际收到的观测点与预测点结算,预占的剩余额度退回。

4. 响应字段

字段说明
request_id服务端请求 ID,与响应头 X-Request-Id 相同。
model_used实际运行的模型 ID:hora-1.0,请求使用别名 hora 时也是如此。
freq传入 freq 时原样返回;省略时返回推断出的规范写法(如 h、15min、MS)。
point_quantileBeta。仅在请求传了 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_reportBeta。{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_reportcleaning_report/1 结构化清洗报告(Beta);raw 预设下不返回。见清洗策略与清洗报告。

5. 响应示例

数值仅为示意,cleaning_report 已折叠:

forecast-response.json
{
  "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 等清洗参数同时使用(422 CLEANING_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:

raw-input-invalid.json
{
"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),不做任何截断。