集成

通过我们的API，您可以为您的产品或者系统集成时序预测能力。

目前，我们提供了预测的API，微调暂时还未支持，对于光伏、风电、负荷预测，建议您先在我们的产品官网上先使用自己的数据进行微调后，再进行预测。

前置说明

在使用API之前，需要您确保：

在曦谋决策官网创建了APIKey，如果未创建请参考密钥管理部分。
如果需要使用付费的接口，需要账户有调用余额。

整体使用流程

我们使用了异步任务的方式来提供API，包含创建任务和查询任务结果的功能。

通过创建任务，您可以提交您的预测需求到系统；
通过查询任务，您可以跟踪任务状态，并在任务完成后获得预测的结果。

下图展示了 API 的基本使用流程。

调用流程

创建预测任务

1. 通用时序预测任务

请求参数

参数名	说明	类型/格式	是否必填	默认值
`inputModelKey`	使用的模型 `key`	字符串	是	无
`freq`	预测时间间隔，支持：`FIVE_MIN`（5分钟）、`FIFTEEN_MIN`（15分钟）、`THIRTY_MIN`（30分钟）、`ONE_H`（1小时）、`ONE_D`（每日）	枚举类型	否	FIFTEEN_MIN（15分钟）
`extraInfo.type`	模型类型	字符串	是	固定填`MOE`
`extraInfo.modelKey`	额外参数中携带的模型标识	字符串	是	固定填`time_moe_base`
`extraInfo.historyFileUri`	历史文件链接	字符串	是	需要给一个公网可以访问的文件链接
`extraInfo.historyFileColTime`	文件中用来表示时间的列名	字符串	是	无
`extraInfo.historyFileColTarget`	文件中用来表示预测值的列名	字符串	是	无
`extraInfo.horizon`	预测数据的长度	整数，必须大于0	是	无

请求示例

Curl

curl -X POST 'https://time.xm-opt.com/api/solar_power_predict_async' \
--header 'Content-Type: application/json' \
--header 'apikey: <apikey>' \
--data-raw '{
  "inputModelKey": "time_moe_base",
  "freq": "FIFTEEN_MIN",
  "extraInfo": {
    "type": "MOE",
    "modelKey":"time_moe_base",
    "historyFileUri": "f4cf53c0-86e4-4a0a-a5d5-d878d0937e24/file/moe_10_days_example (1).csv",
    "historyFileColTime": "time",
    "historyFileColTarget": "pv_power",
    "horizon": "96"
  }
}'

注意这里的historyFileUri字段需要设置成一个公网可以访问的文件链接。

Python

所有接口的Python示例，主要是将上边curl请求的--data-raw后的JSON数据原封不动的替换到下方的data字典中。因此后续类似的接口只给出curl请求示例，将不再提供Python示例。

import requests

url = 'https://time.xm-opt.com/api/solar_power_predict_async'
headers = {
    'Content-Type': 'application/json',
    'apikey': '<apikey>'
}
data = {
  "inputModelKey": "time_moe_base",
  "freq": "FIFTEEN_MIN",
  "extraInfo": {
    "type": "MOE",
    "modelKey":"time_moe_base",
    "historyFileUri": "f4cf53c0-86e4-4a0a-a5d5-d878d0937e24/file/moe_10_days_example (1).csv",
    "historyFileColTime": "time",
    "historyFileColTarget": "pv_power",
    "horizon": "96"
  }
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

返回示例

{
    "code": 0,
    "message": null,
    "requestId": null,
    "data": {
        "taskKey": "2c9d1a14-60f7-4d78-a402-ebf3af95ee2a"
    },
    "success": true
}

2. 分布式光伏功率预测任务

请求参数

参数名	说明	类型/格式	是否必填	默认值
`inputModelKey`	使用的模型 `key`，使用微调页面上展示的模型key	字符串	是	无
`longitude`	经度，精度到小数点后3位	小数，3位精度	是	无
`latitude`	纬度，精度到小数点后3位	小数，3位精度	是	无
`capacity`	系统的额定功率，即在标准测试条件下可输出的最大功率，单位为千瓦(KW)	整数	是	无
`freq`	预测时间间隔，支持：`FIVE_MIN`（5分钟）、`FIFTEEN_MIN`（15分钟）、`THIRTY_MIN`（30分钟）、`ONE_H`（1小时）、`ONE_D`（每日）	枚举类型	否	FIFTEEN_MIN（15分钟）
`altitude`	高度 / 海拔，单位米	整数/小数	否	地表高度
`tiltAngle`	倾斜角（单位：度°），范围 0–90°	整数/小数（0~90）	否	与纬度相同
`orientationAngle`	朝向角（单位：度°），180° 为正南	整数/小数（0~360）	否	180
`extraInfo.type`	模型类型	字符串	是	固定填`TIMELLM`
`extraInfo.modelKey`	微调基础模型标识	字符串	是	固定填`solar_power_default`
`extraInfo.startDate`	预测起始日期，包含	字符串，格式类似`2025-04-21`	是	无
`extraInfo.endDate`	预测结束日期，包含	字符串，格式类似`2025-04-21`	是	无

请求示例

curl

curl -X POST 'https://time.xm-opt.com/api/solar_power_predict_async' \
--header 'Content-Type: application/json' \
--header 'apikey: <apikey>' \
--data-raw '{
    "inputModelKey": "<model_key>",
    "freq": "FIFTEEN_MIN",
    "longitude": 120,
    "latitude": 30,
    "capacity": 10,
    "extraInfo": {
        "type": "TIMELLM",
        "modelKey": "solar_power_default",
        "startDate": "2025-04-21",
        "endDate": "2025-04-22"
    }
}'

python

import requests

url = 'https://time.xm-opt.com/api/solar_power_predict_async'
headers = {
    'Content-Type': 'application/json',
    'apikey': '<apikey>'
}
data = {
    "inputModelKey": "<model_key>",
    "freq": "FIFTEEN_MIN",
    "longitude": 120,
    "latitude": 30,
    "capacity": 10,
    "extraInfo": {
        "type": "TIMELLM",
        "modelKey": "solar_power_default",
        "startDate": "2025-04-21",
        "endDate": "2025-04-22"        
    }
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

返回示例

{
    "code": 0,
    "message": null,
    "requestId": null,
    "data": {
        "taskKey": "2c9d1a14-60f7-4d78-a402-ebf3af95ee2a"
    },
    "success": true
}

3. 风电场站功率预测任务

请求参数

参数名	说明	类型/格式	是否必填	默认值
`inputModelKey`	使用微调出来的模型 `key`，请参考模型微调页面	字符串	是	无
`longitude`	经度，精度到小数点后3位	小数，3位精度	是	无
`latitude`	纬度，精度到小数点后3位	小数，3位精度	是	无
`capacity`	最大功率，即在标准测试条件下可输出的最大功率，单位下方参数可配置	整数	是	无
`freq`	预测时间间隔，支持：`FIVE_MIN`（5分钟）、`FIFTEEN_MIN`（15分钟）、`THIRTY_MIN`（30分钟）、`ONE_H`（1小时）、`ONE_D`（每日）	枚举类型	否	FIFTEEN_MIN（15分钟）
`extraInfo.type`	模型类型	字符串	是	固定填`WIND_DEFAULT`
`extraInfo.modelKey`	基础模型的 `key`	字符串	是	固定填`wind_power_default`
`extraInfo.capUnit`	最大功率的单位	字符串	是	`KW`或者`MW`
`extraInfo.cutIn`	切入风速，单位m/s	整数/小数	否	3
`extraInfo.cutOut`	切出风速，单位m/s	整数/小数	否	25
`extraInfo.rated`	额定风速，单位m/s	整数/小数	否	12
`extraInfo.hubHeight`	风机高度，单位米	整数/小数	否	100
`extraInfo.startDate`	预测起始日期，包含	字符串，格式类似`2025-04-21`	是	无
`extraInfo.endDate`	预测结束日期，包含	字符串，格式类似`2025-04-21`	是	无

请求示例

Curl

curl -X POST 'https://time.xm-opt.com/api/solar_power_predict_async' \
--header 'Content-Type: application/json' \
--header 'apikey: <apikey>' \
--data-raw '{
  "inputModelKey": "<modelKey>",
  "freq": "FIFTEEN_MIN",
  "longitude": 121,
  "latitude": 32,
  "capacity": 300,  
  "extraInfo": {
    "type": "WIND_DEFAULT",
    "modelKey":"wind_power_default",
    "capUnit":"KW",
    "cutIn": 3,
    "cutOut": 25,
    "rated": 12,
    "hubHeight": 120,
    "startDate":"2025-04-21",
    "endDate":"2025-04-22"   
  }
}'

Python

参考通用时序预测的说明。

返回示例

{
    "code": 0,
    "message": null,
    "requestId": null,
    "data": {
        "taskKey": "2c9d1a14-60f7-4d78-a402-ebf3af95ee2a"
    },
    "success": true
}

4. 负荷预测任务

请求参数

参数名	说明	类型/格式	是否必填	默认值
`inputModelKey`	使用的模型 `key`，使用微调页面上展示的模型key	字符串	是	无
`longitude`	经度，精度到小数点后3位	小数，3位精度	是	无
`latitude`	纬度，精度到小数点后3位	小数，3位精度	是	无
`freq`	预测时间间隔，支持：`FIVE_MIN`（5分钟）、`FIFTEEN_MIN`（15分钟）、`THIRTY_MIN`（30分钟）、`ONE_H`（1小时）、`ONE_D`（每日）	枚举类型	否	FIFTEEN_MIN（15分钟）
`extraInfo.type`	模型类型	字符串	是	固定填写`LOAD_DEFAULT`
`extraInfo.modelKey`	微调基础模型key	字符串	是	固定填写`load_default`
`extraInfo.startDate`	预测起始日期，包含	字符串，格式类似`2025-04-21`	是	无
`extraInfo.endDate`	预测结束日期，包含	字符串，格式类似`2025-04-21`	是	无

请求示例

Curl

curl -X POST 'https://time.xm-opt.com/api/solar_power_predict_async' \
--header 'Content-Type: application/json' \
--header 'apikey: <apikey>' \
--data-raw '{
    "inputModelKey": "<model_key>",
    "freq": "FIFTEEN_MIN",
    "longitude": 120,
    "latitude": 30,
    "extraInfo": {
        "type": "LOAD_DEFAULT",
        "modelKey": "load_default",
        "startDate":"2025-04-21",
        "endDate":"2025-04-22"          
    }
}'

Python

参考通用时序预测的说明。

结果示例

{
    "code": 0,
    "message": null,
    "requestId": null,
    "data": {
        "taskKey": "2c9d1a14-60f7-4d78-a402-ebf3af95ee2a"
    },
    "success": true
}

查询预测任务结果

请求示例

curl

curl -X GET 'https://time.xm-opt.com/api/solar_power_predict_async_result?taskKey=<taskKey>' \
--header 'Content-Type: application/json' \
--header 'apikey: <api_key>'

python

import requests

url = 'https://time.xm-opt.com/api/solar_power_predict_async_result'
headers = {
    'Content-Type': 'application/json',
    'apikey': 'your apikey'
}

# 设置查询参数（将 <your_task_key> 替换为实际的 taskKey）
params = {
    "taskKey": "<your_task_key>"
}

# 发送 GET 请求
response = requests.get(url, headers=headers, params=params)

# 打印响应结果
print(response.json())

响应状态

PENDING # 任务排队等待中
RUNNING # 任务运行中
COMPLETED # 任务已完成
FAILED # 任务失败

响应示例

{
    "code": 0,
    "message": null,
    "requestId": null,
    "data": {
        "taskStatus": "COMPLETED",
        "predictResult": {
            "datetime": [
                "2024-10-22 00:15:00+08:00",
                "2024-10-22 00:30:00+08:00",
                "2024-10-22 00:45:00+08:00",
                "2024-10-22 01:00:00+08:00",
                "2024-10-22 01:15:00+08:00",
                "2024-10-22 01:30:00+08:00",
                "2024-10-22 01:45:00+08:00",
                "2024-10-22 02:00:00+08:00",
                "2024-10-22 02:15:00+08:00",
                "2024-10-22 02:30:00+08:00",
                "2024-10-22 02:45:00+08:00",
                "2024-10-22 03:00:00+08:00",
                "2024-10-22 03:15:00+08:00",
                "2024-10-22 03:30:00+08:00",
                "2024-10-22 03:45:00+08:00",
                "2024-10-22 04:00:00+08:00",
                "2024-10-22 04:15:00+08:00",
                "2024-10-22 04:30:00+08:00",
                "2024-10-22 04:45:00+08:00",
                "2024-10-22 05:00:00+08:00",
                "2024-10-22 05:15:00+08:00",
                "2024-10-22 05:30:00+08:00",
                "2024-10-22 05:45:00+08:00",
                "2024-10-22 06:00:00+08:00",
                "2024-10-22 06:15:00+08:00",
                "2024-10-22 06:30:00+08:00",
                "2024-10-22 06:45:00+08:00",
                "2024-10-22 07:00:00+08:00",
                "2024-10-22 07:15:00+08:00",
                "2024-10-22 07:30:00+08:00",
                "2024-10-22 07:45:00+08:00",
                "2024-10-22 08:00:00+08:00",
                "2024-10-22 08:15:00+08:00",
                "2024-10-22 08:30:00+08:00",
                "2024-10-22 08:45:00+08:00",
                "2024-10-22 09:00:00+08:00",
                "2024-10-22 09:15:00+08:00",
                "2024-10-22 09:30:00+08:00",
                "2024-10-22 09:45:00+08:00",
                "2024-10-22 10:00:00+08:00",
                "2024-10-22 10:15:00+08:00",
                "2024-10-22 10:30:00+08:00",
                "2024-10-22 10:45:00+08:00",
                "2024-10-22 11:00:00+08:00",
                "2024-10-22 11:15:00+08:00",
                "2024-10-22 11:30:00+08:00",
                "2024-10-22 11:45:00+08:00",
                "2024-10-22 12:00:00+08:00",
                "2024-10-22 12:15:00+08:00",
                "2024-10-22 12:30:00+08:00",
                "2024-10-22 12:45:00+08:00",
                "2024-10-22 13:00:00+08:00",
                "2024-10-22 13:15:00+08:00",
                "2024-10-22 13:30:00+08:00",
                "2024-10-22 13:45:00+08:00",
                "2024-10-22 14:00:00+08:00",
                "2024-10-22 14:15:00+08:00",
                "2024-10-22 14:30:00+08:00",
                "2024-10-22 14:45:00+08:00",
                "2024-10-22 15:00:00+08:00",
                "2024-10-22 15:15:00+08:00",
                "2024-10-22 15:30:00+08:00",
                "2024-10-22 15:45:00+08:00",
                "2024-10-22 16:00:00+08:00",
                "2024-10-22 16:15:00+08:00",
                "2024-10-22 16:30:00+08:00",
                "2024-10-22 16:45:00+08:00",
                "2024-10-22 17:00:00+08:00",
                "2024-10-22 17:15:00+08:00",
                "2024-10-22 17:30:00+08:00",
                "2024-10-22 17:45:00+08:00",
                "2024-10-22 18:00:00+08:00",
                "2024-10-22 18:15:00+08:00",
                "2024-10-22 18:30:00+08:00",
                "2024-10-22 18:45:00+08:00",
                "2024-10-22 19:00:00+08:00",
                "2024-10-22 19:15:00+08:00",
                "2024-10-22 19:30:00+08:00",
                "2024-10-22 19:45:00+08:00",
                "2024-10-22 20:00:00+08:00",
                "2024-10-22 20:15:00+08:00",
                "2024-10-22 20:30:00+08:00",
                "2024-10-22 20:45:00+08:00",
                "2024-10-22 21:00:00+08:00",
                "2024-10-22 21:15:00+08:00",
                "2024-10-22 21:30:00+08:00",
                "2024-10-22 21:45:00+08:00",
                "2024-10-22 22:00:00+08:00",
                "2024-10-22 22:15:00+08:00",
                "2024-10-22 22:30:00+08:00",
                "2024-10-22 22:45:00+08:00",
                "2024-10-22 23:00:00+08:00",
                "2024-10-22 23:15:00+08:00",
                "2024-10-22 23:30:00+08:00",
                "2024-10-22 23:45:00+08:00",
                "2024-10-23 00:00:00+08:00"
            ],
            "predictPower": [
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.5965,
                0.7952,
                4.0249,
                7.2533,
                10.4804,
                13.7062,
                15.8896,
                18.0726,
                20.2552,
                22.4373,
                19.852,
                17.2678,
                14.6846,
                12.1024,
                12.849,
                13.5959,
                14.3431,
                15.0906,
                18.3172,
                21.5438,
                24.7704,
                27.997,
                33.911,
                39.8273,
                45.7461,
                51.6672,
                54.7308,
                57.7926,
                60.8525,
                63.9106,
                67.7809,
                71.6513,
                75.5216,
                79.392,
                74.1323,
                68.8726,
                63.6128,
                58.3531,
                50.9101,
                43.4671,
                36.0241,
                28.5811,
                22.329,
                16.0769,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0
            ],
            "predictEnergy": null
        },
        "taskKey": "19eee177-05b2-4e91-aef1-7a4e6feddae0"
    },
    "success": true
}

前置说明​

整体使用流程​

创建预测任务​

1. 通用时序预测任务​

请求参数​

请求示例​

Curl​

Python​

返回示例​

2. 分布式光伏功率预测任务​

请求参数​

请求示例​

curl​

python​

返回示例​

3. 风电场站功率预测任务​

请求参数​

请求示例​

Curl​

Python​

返回示例​

4. 负荷预测任务​

请求参数​

请求示例​

Curl​

Python​

结果示例​

查询预测任务结果​

请求示例​

curl​

python​

响应状态​

响应示例​

前置说明

整体使用流程

创建预测任务

1. 通用时序预测任务

请求参数

请求示例

Curl

Python

返回示例

2. 分布式光伏功率预测任务

请求参数

请求示例

curl

python

返回示例

3. 风电场站功率预测任务

请求参数

请求示例

Curl

Python

返回示例

4. 负荷预测任务

请求参数

请求示例

Curl

Python

结果示例

查询预测任务结果

请求示例

curl

python

响应状态

响应示例