批量下载任务

1. 基础信息

• Base URL：https://api.mirror-earth.com
• 鉴权方式：API Key（无需登录）
• 请求头：
  • X-API-Key: <apikey>
  • Content-Type: application/json

---

2. 获取 API Key

API Key 在个人中心查看。请妥善保存，不要泄露。

---

3. 接口列表

• 查询当日用量：GET /api/tasks/usage
• 创建任务：POST /api/tasks/export
• 预估任务：POST /api/tasks/estimate
• 获取任务列表：GET /api/tasks
• 获取任务状态：GET /api/tasks/:task_id/status
• 取消任务：POST /api/tasks/:task_id/cancel
• 删除任务：DELETE /api/tasks/:task_id

---

4. 鉴权方式

4.1 Header

X-API-Key: <apikey>

---

5. 查询当日用量

GET /api/tasks/usage

{
  "code": 0,
  "message": "success",
  "data": {
    "daily_completed_bytes": 524288000,
    "daily_reserved_bytes": 104857600,
    "daily_used_bytes": 629145600,
    "daily_limit_bytes": 4294967296,
    "daily_remain_bytes": 3665821696,
    "per_task_limit_bytes": 209715200,
    "active_task_count": 2,
    "active_task_limit": 20
  }
}

所有限额均以接口返回值为准，不应在客户端写死。

---

6. 创建任务

6.1 请求

POST /api/tasks/export

请求头：

X-API-Key: <apikey>
Content-Type: application/json

请求体示例：

{
  "domain": "era5_seamless",
  "hourly": ["dew_point_2m"],
  "daily": [],
  "monthly": [],
  "time_range": {
    "type": "date_range",
    "start": "2025-08-01",
    "end": "2025-08-10"
  },
  "area": {
    "type": "grid",
    "lat_min": 30.0,
    "lat_max": 40.0,
    "lon_min": 110.0,
    "lon_max": 120.0
  },
  "timezone": "Asia/Shanghai",
  "area_average": false,
  "estimate_id": "7cf4ff75-0d6a-45ea-bae6-3f6d3402672f"
}

6.2 字段说明（关键字段）

{
  "domain": "ecmwf_ifs",           // 必填：数据模型，详见13
  "hourly": ["temperature_2m"],    // 可选：小时变量列表（与 daily, monthly 互斥）
  "daily": [],                     // 可选：日变量列表（与 hourly, monthly 互斥）
  "monthly": [],                   // 可选：月变量列表（与 hourly, daily 互斥）
  "time_range": {                  // 必填：时间范围
    "type": "date_range",          // date_range 或 forecast
    "start": "2025-01-01",         // date_range 时必填
    "end": "2025-01-31",           // date_range 时必填
    "start_hour": "2025-11-01T00:00", // forecast 单起报时：UTC ISO 起报时间
    "forecast_hours": 72           // forecast 时可选；省略时使用模型支持的最大时效
  },
  "area": {                        // 必填：空间范围
    "type": "grid",                // grid 或 point

    // === grid 类型参数 ===
    "lat_min": 30.0,               // grid 时必填
    "lat_max": 40.0,               // grid 时必填
    "lon_min": 110.0,              // grid 时必填
    "lon_max": 120.0,              // grid 时必填

    // === point 类型参数（二选一）===
    "adcodes": [                   // 可选：行政区划代码列表（推荐）
      "110000",                    //   北京
      "310000",                    //   上海
      "440000"                     //   广东
    ],
    "locations": [                 // 可选：经纬度列表
      {
        "id": "1",
        "name": "北京",
        "lat": 39.9,
        "lon": 116.4
      },
      {
        "id": "2",
        "name": "上海",
        "lat": 31.2,
        "lon": 121.5
      }
    ]
  },
  "timezone": "Asia/Shanghai",     // 可选：默认 auto
  "area_average": false,           // 可选：默认 false，下载区域平均数据时设为 true
  "estimate_id": "7cf4ff75-0d6a-45ea-bae6-3f6d3402672f" // 可选， 由 /estimate 返回，有效期 10 分钟
}

time_range.type 为 forecast 时有两种用法：

• 单起报模式（兼容）：start_hour 使用 UTC ISO-8601 日期时间，例如 2025-11-01T00:00。输出结构和 forecast_hours 语义保持不变。
• 多起报范围模式（仅历史预报）：当 domain 为历史预报模型且同时提供 start、end 和 start_hour 时，start 与 end 表示包含首尾日期的 UTC 日期范围，start_hour 改为逗号分隔的 UTC 起报小时，例如 00,12。系统按日期升序、同日小时升序生成多个起报时间。

多起报范围模式的限制：

• start_hour 只允许 00、06、12、18，不允许空项、重复值、其他格式或其他小时。
• 仅支持 hourly 或 daily 数据，不支持 monthly。
• 非历史预报模型不能使用小时列表形式的 start_hour。
• 未提供 forecast_hours 时，每个起报时间使用对应模型运行的可用预报时长；提供后会分别校验每个起报时间的最大时效。
• 日期和小时按 UTC 解释，与 timezone 的结果显示时区设置相互独立。

6.3 提交规则

先调用 /api/tasks/estimate，再将返回的 estimate_id 原样传给 /api/tasks/export。estimate_id 与当前 API Key 和请求参数绑定，修改模型、变量、时间范围、区域、分辨率、时区或 area_average 后必须重新预估。

不传 estimate_id 时服务端会同步预估；若预估失败或超时，任务不会创建。单用户最多保留 20 个 pending + processing 任务，最多同时执行 2 个。

6.4 响应示例

{
  "code": 0,
  "message": "任务创建成功",
  "data": {
    "task_id": "515afcc8-8542-40af-a503-69b54190a5a6",
    "status": "pending",
    "estimated_bytes": 12582912,
    "estimate_id": "7cf4ff75-0d6a-45ea-bae6-3f6d3402672f"
  }
}

---

7. 预估任务

POST /api/tasks/estimate

请求体与创建任务相同，但不需要提供 estimate_id。

{
  "code": 0,
  "message": "success",
  "data": {
    "data": {
      "bytes": 12582912,
      "estimation": "12 MB",
      "full_output": "[ INFO ] Estimated output size: 12 MB"
    },
    "error": false,
    "error_msg": "",
    "estimate_id": "7cf4ff75-0d6a-45ea-bae6-3f6d3402672f",
    "estimated_bytes": 12582912,
    "expires_at": "2026-07-16T16:30:00+08:00",
    "limit_bytes": 209715200,
    "limit_msg": "当前用户下载限额: 200MB"
  }
}

预估详情位于 data.data，其中 bytes、estimation 和 full_output 保持旧响应结构；data.error 和 data.error_msg 也继续用于表示 CLI 预估失败原因。只有 error=false 且存在有效 estimate_id 时才可创建任务。

estimate_id、estimated_bytes 和 expires_at 为新增字段；estimate_id 有效期为 10 分钟。预估成功不占用配额，只有创建任务成功后才会预留每日额度。

7.1 推荐调用流程

estimate = requests.post(f"{BASE_URL}/api/tasks/estimate", json=payload, headers=headers)
estimate.raise_for_status()
estimate_data = estimate.json()["data"]
if estimate_data.get("error") or not estimate_data.get("estimate_id"):
    raise RuntimeError(estimate_data.get("error_msg") or "预估失败")

payload["estimate_id"] = estimate_data["estimate_id"]
export = requests.post(f"{BASE_URL}/api/tasks/export", json=payload, headers=headers)
export.raise_for_status()
task_id = export.json()["data"]["task_id"]

7.2 限额与预估错误

---

8. 获取任务列表

GET /api/tasks?page=1&page_size=20&status=processing

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "tasks": [],
    "total": 0,
    "page": 1,
    "page_size": 20
  }
}

---

9. 获取任务进度

GET /api/tasks/:task_id/status

{
  "code": 0,
  "data": {
    "status": "completed",
    "progress_precent": 100,
    "output_file": "126ad0ec-ddf1-4735-a297-a3b3ca61c26f.zip"
  },
  "message": "success"
}

关键字段：

• status：pending | processing | completed | failed | cancelled
• progress_percent：0~100
• output_file：输出文件

10. 下载任务结果

当获取任务状态为completed的时候，可以下载任务结果文件，获取output_file字段，然后拼接： https://api.mirror-earth.com/user_downloads/<output_file>

---

11. 取消任务

POST /api/tasks/:task_id/cancel

仅允许取消 pending 或 processing 状态。

---

12. 删除任务

DELETE /api/tasks/:task_id

仅允许删除 completed / failed / cancelled 状态。

---

13. 常见错误

• 401 未授权：API Key 缺失或无效
• 403 无权访问：任务不属于该用户
• 404 任务不存在

---

14. 可用数据模型(domain)

14.1 预报模型

14.2 历史预报模型

14.3 历史观测/再分析模型

15. 可用数据要素

逐小时要素请点击上方链接，查看各模型的支持
逐日要素点击 逐日要素支持 查看