模型与能力上限

API 提供一个模型：SequenxAI Omni，SequenxAI 的通用时序模型，模型 id 为 hora-1.0，省略 model 时即使用它。浮动别名 hora 指向同一模型；响应的 model_used 始终给出具体 id（hora-1.0）。服务端在清洗和推理前就按下列上限校验请求。

1. 能力上限

模型	最小上下文	最大上下文	最大步长 `h`
`hora-1.0`	16	4,096	1,024

预测跨度等于 h 乘以数据频率，因此同一上限在不同频率下覆盖的时间长度不同：例如 15 分钟数据单次最多 1,024 步（约 10.7 天），小时数据约 42.7 天。

上限来自模型服务的能力清单，服务端每分钟左右刷新一次；清单暂时取不到时，服务端使用内置副本。上限调整时以错误响应里的数值为准：HORIZON_EXCEEDS_MODEL 的 details.max_horizon、SERIES_TOO_LONG 的 details.max_context，以及清洗报告中 too_short_for_model 的 min_context。

2. 上限如何生效

上限	行为
最大步长	`h` 超过上限时直接返回 422 `HORIZON_EXCEEDS_MODEL`，不清洗、不占额度。`h` 本身还受契约 1–2048 的限制。
最大上下文	某个实体长于上限时返回 422 `SERIES_TOO_LONG`，服务端不会替你截断历史。按 `unique_id` 统计模型实际会收到的点数：清洗前看不重复的时间戳数，清洗后看规则网格的长度（补齐的点也算），`raw` 预设看行数。若实体中有达到分段阈值（`options.gap_split_min_steps`）的缺口，清洗可能只保留最新一段，因此清洗前不拦，以清洗后的网格长度为准。不计费。请只发送最近的点。
最小上下文	清洗后（含插值补齐的点）某个实体的点数少于上限时返回 422 `SERIES_TOO_SHORT`。

horizon-exceeds-model.json

{
"error": {
  "code": "HORIZON_EXCEEDS_MODEL",
  "message": "h=1500 exceeds the maximum horizon 1024 of model 'hora-1.0'",
  "request_id": "req_…",
  "details": {"model": "hora-1.0", "h": 1500, "max_horizon": 1024}
}
}

series-too-long.json

{
"error": {
  "code": "SERIES_TOO_LONG",
  "message": "A series is longer than the maximum context of model 'hora-1.0' (4096 points); send only the most recent 4096 points per series",
  "request_id": "req_…",
  "details": {
    "model": "hora-1.0", "max_context": 4096, "measured": "timestamps",
    "series": [{"unique_id": "meter-001", "points": 8760}], "series_count": 1,
    "hint": "Send only the most recent 4096 points of each listed series"
  }
}
}

3. 模型选项

可选对象 model_options 用来切换推理行为。两个键都可省略，省略时取默认值。只对 /v1/forecast 生效（/v1/clean 不运行模型）。

键	取值	默认	行为
`nonnegative`	`"auto"`、`true`、`false`	`"auto"`	`"auto"`：仅当某个实体交给模型的历史全部非负时，才把该实体的预测（`y_hat` 与区间上下界）截断在 0；`true`：总是截断在 0；`false`：从不截断。
`flip_average`	`true`、`false`	`true`	`true`：模型同时预测取负后的历史，翻转回来后与直接预测取平均，推理算力约为两倍，延迟可能增加；`false`：只算一遍。

计费与这些选项无关，仍按预测点计费，flip_average: true 与 false 费用相同。这里的 nonnegative 作用于预测结果，与只约束历史插值的 options.cleaning.nonnegative 无关。

model-options.json

{
"model": "hora-1.0",
"series": [ … ],
"h": 24,
"freq": "1h",
"model_options": {"nonnegative": true, "flip_average": false}
}

model_options 是封闭对象：未知的键返回 422 VALIDATION_ERROR。所选模型不支持的键返回 422 MODEL_OPTION_UNSUPPORTED（details.model、details.unsupported、details.supported）；hora-1.0 两个键都支持。

4. 其他能力说明

缺失值：服务端总是把清洗后填好的值交给模型，model_input[].missing_mode 为 filled；插值点不计入 fed_points，也不计费。有两种情况在 model_input[] 中单独报告：策略版本 2026-12 起保留的末尾空值不作为数据使用（masked_tail、tail_handling）；传 options.cleaning.long_gap: "mask" 时，模型把内部长缺口读作缺失值而非补值，该条目以 long_gap_points 与 long_gap_handling: "mask" 报告。
分位点：hora-1.0 原生输出 0.01、0.05、0.10、0.15 … 0.90、0.95、0.99。服务不插值，非原生分位数的处理见预测区间。
协变量：该模型目前不使用协变量。API 照常接受协变量列（每个实体最多 8 列）并逐列报告，model_input[].covariates_used 为 false，通过数据检查的列报告 model_unsupported。以 model_input[].covariates 的逐列报告为准；见协变量支持现状。
暂不可用：模型临时不可用时返回 503 SERVICE_UNAVAILABLE，不计费，可稍后重试；模型繁忙时返回 503 MODEL_BUSY 并带 Retry-After。
其他取值：hora-1.0 与 hora 以外的任何 model 都在额度预占之前返回 422 MODEL_NOT_AVAILABLE，details.available 列出可用的 id。

model-not-available.json

{
"error": {
  "code": "MODEL_NOT_AVAILABLE",
  "message": "Model 'my-model' is not available; use 'hora-1.0'",
  "request_id": "req_…",
  "details": {"model": "my-model", "available": ["hora", "hora-1.0"]}
}
}