API.md

# Kronos API 文档

本文档提供有关 Kronos 预测服务的 API 端点的详细信息。

## 基础 URL

基础 URL 将取决于您的部署环境。
-   **本地 Docker**: `http://localhost:7860`
-   **Hugging Face Spaces**: `https://<your-space-name>.hf.space`

## 身份验证

所有端点（`/api/model-status` 除外）都受到保护，需要 API 密钥。密钥必须在请求的 `Authorization` 头中提供。

-   **Header**: `Authorization: Bearer <YOUR_API_KEY>`

未能提供有效密钥将导致 `401 Unauthorized` 错误。

---

## 端点

### 1. 获取可用模型列表

获取服务端所有可用模型的详细信息。

-   **URL**: `/api/available-models`
-   **方法**: `GET`
-   **身份验证**: 不需要。

**成功响应 (200 OK)**
```json
{
  "kronos-mini": {
    "name": "Kronos-mini",
    "model_id": "NeoQuasar/Kronos-mini",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-2k",
    "context_length": 2048,
    "params": "4.1M",
    "description": "Lightweight model, suitable for fast prediction"
  },
  "kronos-small": {
    "name": "Kronos-small",
    "model_id": "NeoQuasar/Kronos-small",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "24.7M",
    "description": "Small model, balanced performance and speed"
  },
  "kronos-base": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}
```

### 2. 获取当前模型状态

检查当前是否有模型被加载到内存中，并返回其详细信息。

-   **URL**: `/api/model-status`
-   **方法**: `GET`
-   **身份验证**: 不需要。

**成功响应 (200 OK)**
```json
{
  "status": "loaded",
  "model_key": "kronos-base",
  "model_info": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}
```

**模型未加载响应 (200 OK)**
```json
{
  "status": "not_loaded"
}
```

### 3. 加载模型

手动将一个指定的模型加载到内存中。

-   **URL**: `/api/load-model`
-   **方法**: `POST`
-   **身份验证**: 需要。

**请求体 (Request Body)**
```json
{
  "model_key": "kronos-base",
  "force_reload": false
}
```
-   `model_key` (可选): 模型的键名。默认为 `kronos-base`。**该值必须是 `/api/available-models` 端点返回的键之一** (例如, `"kronos-mini"`)。
-   `force_reload` (可选): 如果为 `true`，即使请求的模型已在内存中，也会强制重新加载。默认为 `false`。

**成功响应 (200 OK)**
```json
{
  "status": "Model 'Kronos-base' loaded successfully.",
  "model_info": {
    "name": "Kronos-base",
    "model_id": "NeoQuasar/Kronos-base",
    "tokenizer_id": "NeoQuasar/Kronos-Tokenizer-base",
    "context_length": 512,
    "params": "102.3M",
    "description": "Base model, provides better prediction quality"
  }
}
```

**错误响应 (400 Bad Request)**
如果提供了无效的 `model_key`。
```json
{
  "error": "Invalid model_key. Please choose from the allowed models.",
  "allowed_models": [
    "kronos-mini",
    "kronos-small",
    "kronos-base"
  ]
}
```

### 4. 获取预测结果

提交 K 线数据并接收预测结果。

-   **URL**: `/api/predict_from_data`
-   **方法**: `POST`
-   **身份验证**: 需要。

**请求体 (Request Body)**
```json
{
  "k_lines": [
    [1711324800000, "18.545", "19.514", "18.385", "19.395", "2080487", ...],
    [1711411200000, "19.397", "20.759", "19.356", "20.032", "3020519", ...],
    [1711497600000, "20.030", "20.211", "19.011", "19.303", "2351359", ...]
  ],
  "prediction_params": {
    "pred_len": 120
  }
}
```
-   `k_lines` (必需): 代表 K 线数据的数组的数组。格式应与币安 API 标准响应匹配（时间戳, 开盘价, 最高价, 最低价, 收盘价, 成交量, ...）。模型仅使用前 6 列。
-   `prediction_params` (可选): 用于预测参数的字典。
    -   `pred_len` (可选): 要预测的未来时间步数。默认为 `120`。

**成功响应 (200 OK)**
```json
{
  "success": true,
  "prediction_params": {
    "pred_len": 120
  },
  "prediction_results": [
    {
      "timestamp": "2024-07-01T00:00:00",
      "open": 150.1,
      "high": 152.3,
      "low": 149.8,
      "close": 151.5,
      "volume": 100000.0
    },
    {
      "timestamp": "2024-07-01T01:00:00",
      "open": 151.5,
      "high": 153.0,
      "low": 151.0,
      "close": 152.8,
      "volume": 120000.0
    }
  ]
}
```
*(注意: `prediction_results` 是一个示例；实际值会有所不同。)*

**错误响应 (400 Bad Request)**
如果模型尚未加载。
```json
{
  "error": "模型未加载。请先调用 /api/load-model。"
}