API 接入

返回山东 16 市的预报覆盖结果。

OpenAPI

服务地址 http://127.0.0.1:8000

POST`/api/v1/analyze`

multipart/form-data

请求参数
参数	说明
`image`必填	本地图片、HTTPS URL 或 Base64，仅传一个。
`threshold`可选	覆盖比例超过此值时受影响。默认 `0.3`，范围 `(0,1)`。

请求示例

在客户端执行

读取客户端的 ./weather.jpg。

curl http://127.0.0.1:8000/api/v1/analyze \
  -F 'image=@./weather.jpg'

import requests

with open("./weather.jpg", "rb") as image:
    response = requests.post(
        "http://127.0.0.1:8000/api/v1/analyze",
        files={"image": image},
    )
print(response.json())

替换为实际的 HTTPS 图片地址。

curl http://127.0.0.1:8000/api/v1/analyze \
  --form-string 'image=https://image.nmc.cn/product/weather.jpg'

import requests

response = requests.post(
    "http://127.0.0.1:8000/api/v1/analyze",
    files={"image": (None, "https://image.nmc.cn/product/weather.jpg")},
)
print(response.json())

cURL 读取无换行的 weather.b64；Python 直接编码图片。

curl http://127.0.0.1:8000/api/v1/analyze \
  -F 'image=<./weather.b64'

import base64
import requests

with open("./weather.jpg", "rb") as image:
    encoded = base64.b64encode(image.read()).decode("ascii")
response = requests.post(
    "http://127.0.0.1:8000/api/v1/analyze",
    files={"image": (None, encoded)},
)
print(response.json())

调用说明

默认上限：15 MiB、210 万像素。
跨机器调用：将请求中的 127.0.0.1:8000 换为服务器地址。
将 ./weather.jpg 换为客户端图片路径，服务端接收文件内容。
Python 依赖：python3 -m pip install requests。Windows 可用 python。
URL 仅支持配置允许的 HTTPS 主机，默认 image.nmc.cn。
Base64 支持标准编码或图片 data URL，保留补位且不含空白或换行。
Content-Type 由客户端自动生成。自定义阈值：cURL 加 -F 'threshold=0.4'；Python 加 data={"threshold": 0.4}。

响应结构JSON · 16 市

JSONC · 字段注释

{
  "product": "全国强降雨落区预报图", // 产品标题。
  "valid_time": "2026-10-20 08:00 至 2026-10-21 08:00", // 预报有效时段；未识别时省略。
  "published_at": "2026-10-20 06:00", // 图上发布时间；未识别时省略。
  "recognition_mode": "catalog", // catalog：已知产品；generic_legend：通用图例。
  "cities": [ // 山东 16 市的覆盖结果。
    {
      "city": "济南市", // 地级市名称。
      "affected": true, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.4, // 城市总覆盖面积 ÷ 城市面积，0–1。
      "detail": { // 有覆盖时返回的明细；无覆盖时省略。
        "hazard": "强降雨", // 产品灾种，例如强降雨。
        "max_level": "大雨", // 最高图例档位；通用图例模式下省略。
        "dominant_level": "大雨", // 覆盖面积最大的档位。
        "legend_range": "25-50mm", // 最高或主要档位的数值范围。
        "coverage_ratio": 0.4, // 该灾种在城市内的总覆盖比例，与城市总比例相同。
        "affected_area_km2": 3256.0, // 城市内近似覆盖面积，平方千米。
        "level_breakdown": [ // 仅包含覆盖比例大于 0 的档位。
          {
            "level": "大雨", // 该档位名称。
            "legend_range": "25-50mm", // 该档位的数值范围。
            "coverage_ratio": 0.4, // 该档位覆盖面积 ÷ 城市面积，0–1。
            "affected_area_km2": 3256.0 // 该档位近似覆盖面积，平方千米。
          }
        ]
      }
    },
    {
      "city": "青岛市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "淄博市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "枣庄市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "东营市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "烟台市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "潍坊市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "济宁市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "泰安市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "威海市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "日照市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "临沂市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "德州市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "聊城市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "滨州市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    },
    {
      "city": "菏泽市", // 地级市名称。
      "affected": false, // 城市总覆盖比例严格大于 threshold 时为 true。
      "coverage_ratio": 0.0 // 城市总覆盖面积 ÷ 城市面积，0–1。
    }
  ],
  "legend": [ // 输入图片中识别出的图例。
    {
      "level": "大雨", // 图例档位名称。
      "legend_range": "25-50mm", // 图例数值范围。
      "color_rgb": [62, 174, 93] // 实际颜色 [红, 绿, 蓝]，各分量 0–255。
    }
  ],
  "visualization": { // 用于底图叠加的配准信息。
    "input_width": 821, // 输入图片宽度，像素。
    "input_height": 679, // 输入图片高度，像素。
    "image_to_canonical": [1, 0, 0, 1, 0, 0] // 输入像素到山东底图坐标的 SVG 仿射矩阵 [a,b,c,d,e,f]。
  }
}

结构示意，非实际预报。// 为说明注释，实际响应为无注释的 JSON；可空字段可能省略。

字段说明

product产品标题。
valid_time预报有效时段；未识别时省略。
published_at图上发布时间；未识别时省略。
recognition_modecatalog：已知产品；generic_legend：通用图例。
cities[]山东 16 市的覆盖结果。
- city地级市名称。
- affected城市总覆盖比例严格大于 threshold 时为 true。
- coverage_ratio城市总覆盖面积 ÷ 城市面积，0–1。
- detail有覆盖时返回的明细；无覆盖时省略。
  - hazard产品灾种，例如强降雨。
  - max_level最高图例档位；通用图例模式下省略。
  - dominant_level覆盖面积最大的档位。
  - legend_range最高或主要档位的数值范围。
  - coverage_ratio该灾种在城市内的总覆盖比例，与城市总比例相同。
  - affected_area_km2城市内近似覆盖面积，平方千米。
  - level_breakdown[]仅包含覆盖比例大于 0 的档位。
    - level该档位名称。
    - legend_range该档位的数值范围。
    - coverage_ratio该档位覆盖面积 ÷ 城市面积，0–1。
    - affected_area_km2该档位近似覆盖面积，平方千米。
legend[]输入图片中识别出的图例。
- level图例档位名称。
- legend_range图例数值范围。
- color_rgb实际颜色 [红, 绿, 蓝]，各分量 0–255。
visualization用于底图叠加的配准信息。
- input_width输入图片宽度，像素。
- input_height输入图片高度，像素。
- image_to_canonical输入像素到山东底图坐标的 SVG 仿射矩阵 [a,b,c,d,e,f]。

错误码

HTTP 错误码
状态	code	处理
415	`unsupported_media_type`	使用 multipart 表单。
422	`invalid_request`	检查必填项、重复字段和 threshold。
422	`invalid_base64`	检查编码、补位和空白。
413	`file_too_large / remote_image_too_large`	缩小图片后重试。
422	`invalid_image / image_too_large / image_too_small`	检查文件和分辨率。
422	`remote_url_not_allowed / remote_image_unreachable`	检查图片地址、允许主机与服务器网络。
422	`registration_failed`	换用边界清晰、投影符合要求的图片。
503	`analysis_busy`	稍后重试。

结果表示预报图覆盖，不代表灾害已发生。

POST/api/v1/analyze

请求示例

字段说明

POST`/api/v1/analyze`