SeaLegs AI 海洋预报 API

获取全球任意位置的 AI 驱动海洋天气预报。包含风速、浪高、能见度、降水分析，并提供 GO/CAUTION/NO-GO 安全等级分类。

功能特性

• SpotCast 预报：支持全球任意坐标点的海洋天气预报
• AI 安全分析：每日提供 GO / CAUTION / NO-GO 安全等级分类
• 船舶定制化：根据船型和尺寸提供个性化建议
• 多语言支持：支持英文、西班牙语、法语、葡萄牙语、意大利语、日语

设置步骤

1. 获取 API 密钥

1. 访问 https://developer.sealegs.ai 注册账号 —— 您将获得 10 个免费积分 开始使用
2. 在仪表板中生成 API 密钥
3. 如需更多？随时充值（$10 = 200 次预报天数）

2. 配置 OpenClaw

在您的 OpenClaw 配置中添加：

{
  skills: {
    entries: {
      "sealegs-marine-forecast": {
        enabled: true,
        apiKey: "sk_live_your_key_here"
      }
    }
  }
}

或设置环境变量：

export SEALEGS_API_KEY=sk_live_your_key_here

3. 安装技能

clawhub install sealegs-marine-forecast

使用示例

// 迈阿密，佛罗里达州
POST /v3/spotcast
{
  "latitude": 25.7617,
  "longitude": -80.1918,
  "start_date": "2026-02-10T00:00:00Z",
  "num_days": 2,
  "vessel_info": {"type": "sailboat", "length_ft": 35}  // 可选
}

示例响应：

{
  "id": "spc_FrZdSAs6T3cxbXiPtNZvxu",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "forecast_period": {
    "start_date": "2026-02-10T00:00:00-05:00",
    "end_date": "2026-02-11T23:59:59-05:00",
    "num_days": "2"
  },
  "trip_duration_hours": "12",
  "metadata": {
    "location_name": "迈阿密码头"
  },
  "latest_forecast": {
    "status": "completed",
    "ai_analysis": {
      "summary": "两天天气条件理想，风力微弱",
      "daily_classifications": [
        {
          "date": "2026-02-10",
          "classification": "GO",
          "short_summary": "全天条件极佳，风力低于 7 节，海浪平静，1.1-1.6 英尺。最佳出航时段为上午 5:00 至中午 12:00，西北风几乎无风（1-4 节），海浪舒适，1.4 英尺，周期 11 秒。",
          "summary": "周一全天航行条件极佳，风力极其微弱，海况平静。清晨时段为最佳窗口期，西北风接近无风（1-4 节），海浪舒适，1.4 英尺，周期 11 秒，来自东北方向。"
        },
        {
          "date": "2026-02-11",
          "classification": "GO",
          "short_summary": "全天条件优异，风力极轻（1-6 节），浪高极小（1.2-1.3 英尺）。最佳时段为上午 9:00 至下午 1:00，呈现镜面般平静，风力 1-3 节，浪高 1.2 英尺，周期 11 秒。",
          "summary": "周二全天航海条件优异，风力微弱，浪高极小。上午至中午时段提供理想镜面状态，东风偏南风力 1-3 节，浪高 1.2 英尺，周期 10-11 秒，来自东北方向。"
        }
      ]
    }
  }
}

API 端点

使用的气象因素

• 风速、阵风及风向
• 浪高、周期及波向
• 能见度与雾概率
• 降水概率与强度
• 空气与水温

认证方式

所有请求需包含：

Authorization: Bearer $SEALEGS_API_KEY
Content-Type: application/json

请求频率限制

• 标准套餐：每分钟 60 次请求
• 所有响应均包含速率限制头信息：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset

计费规则

• 每次预报天数计为 1 积分（3 天预报 = 3 积分）
• GET 类操作免费
• 刷新操作每次预报天数收费 1 积分

SpotCast 预报

SpotCast 为指定地理坐标生成基于 AI 的海洋天气预报。

创建 SpotCast

POST https://api.sealegs.ai/v3/spotcast

创建新的预报请求。处理为异步操作（通常耗时 30-60 秒）。

必填参数：

• latitude (数字): -90 至 90
• longitude (数字): -180 至 180
• start_date (字符串): ISO 8601 格式（例如："2025-12-05T00:00:00Z"）
• num_days (整数): 1-5

可选参数：

• webhook_url (字符串): HTTPS 回调地址，用于完成通知
• metadata (对象): 自定义键值对，供您参考
• trip_duration_hours (整数): 旅程时长（小时）
• preferences.language: en, es, fr, pt, it, ja（默认：en）
• preferences.distance_units: nm, mi, km（默认：nm）
• preferences.speed_units: kts, mph, ms（默认：kts）
• vessel_info.type: powerBoat, sailboat, pwc, yacht, catamaran
• vessel_info.length_ft: 1-500

示例请求：

curl -X POST https://api.sealegs.ai/v3/spotcast \
  -H "Authorization: Bearer $SEALEGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 25.7617,
    "longitude": -80.1918,
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2,
    "vessel_info": {"type": "sailboat", "length_ft": 35}
  }'

响应 (202 Accepted):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "estimated_completion_seconds": 45,
  "credits_charged": 2,
  "credits_remaining": 98,
  "links": {
    "self": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz",
    "forecast": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecast/fcst_xyz789",
    "status": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status"
  }
}

查询 SpotCast 状态

GET https://api.sealegs.ai/v3/spotcast/{id}/status

轮询此端点，直到状态变为 "completed" 或 "failed"。建议轮询间隔为 10-15 秒。

状态值：

• pending：已排队处理（无 progress 字段）
• processing：正在生成预报（包含 progress 字段）
• completed：已准备就绪，可获取结果（包含 progress，百分比为 100%）
• failed：发生错误

进度阶段（仅在状态为 processing 或 completed 时存在）：

• fetching_weather
• processing_data
• ai_analysis
• completing
• completed（100%）

示例请求：

curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (pending):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "pending",
  "created_at": "2025-12-01T10:30:00Z"
}

响应 (processing):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "progress": {
    "stage": "ai_analysis",
    "percentage": 75
  }
}

响应 (completed):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "completed",
  "created_at": "2025-12-01T10:30:00Z",
  "completed_at": "2025-12-01T10:30:45Z",
  "progress": {
    "stage": "completed",
    "percentage": 100
  }
}

获取 SpotCast

GET https://api.sealegs.ai/v3/spotcast/{id}

获取已完成的预报及 AI 分析结果。

示例请求：

curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (200 OK):

{
  "id": "spc_abc123xyz",
  "created_at": "2025-12-01T10:30:00Z",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "end_date": "2025-12-06T00:00:00Z",
    "num_days": 2
  },
  "trip_duration_hours": 12,
  "forecast_count": 1,
  "metadata": {
    "location_name": "迈阿密码头"
  },
  "latest_forecast": {
    "forecast_id": "fcst_xyz789",
    "status": "completed",
    "created_at": "2025-12-01T10:30:00Z",
    "completed_at": "2025-12-01T10:30:45Z",
    "ai_analysis": {
      "summary": "预计天气状况良好。东北风 8-12 节，海浪平静，1-2 英尺。",
      "daily_classifications": [
        {
          "date": "2025-12-05",
          "classification": "GO",
          "summary": "东北风 8-12 节，海浪 1-2 英尺，能见度极佳，超过 10 海里。无降水预期。"
        },
        {
          "date": "2025-12-06",
          "classification": "CAUTION",
          "summary": "风力增强至 15-20 节，下午海浪增至 3-4 英尺。建议早晨出发。"
        }
      ]
    }
  }
}

刷新 SpotCast

POST https://api.sealegs.ai/v3/spotcast/{id}/refresh

使用最新气象数据更新现有预报。每预报天数收费 1 积分。

可选请求体：

• webhook_url (string)：覆盖本次刷新的 webhook 地址

示例请求：

curl -X POST https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/refresh \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (202 Accepted):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_newxyz789",
  "status": "processing",
  "created_at": "2025-12-02T08:00:00Z",
  "links": {
    "self": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz",
    "status": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status"
  }
}

列出预报

GET https://api.sealegs.ai/v3/spotcast/{id}/forecasts

列出某个 SpotCast 的所有预报，按创建时间排序（最新在前）。每次创建或刷新 SpotCast 时，都会生成一个新的预报。

查询参数：

• limit (integer)：返回结果数量（默认：10）

示例请求：

curl "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecasts?limit=5" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (200 OK):

{
  "spotcast_id": "spc_abc123xyz",
  "data": [
    {
      "forecast_id": "fcst_newxyz789",
      "status": "completed",
      "created_at": "2025-12-02T08:00:00Z",
      "completed_at": "2025-12-02T08:00:42Z"
    },
    {
      "forecast_id": "fcst_xyz789",
      "status": "completed",
      "created_at": "2025-12-01T10:30:00Z",
      "completed_at": "2025-12-01T10:30:45Z"
    }
  ],
  "has_more": false
}

获取特定预报

GET https://api.sealegs.ai/v3/spotcast/{id}/forecast/{forecast_id}

获取指定预报的完整详情，包括 AI 分析内容。可用于访问 SpotCast 历史中的任意预报，而不仅限于最新版本。

示例请求：

curl "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecast/fcst_xyz789" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (200 OK - 已完成):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "completed",
  "created_at": "2025-12-01T10:30:00Z",
  "completed_at": "2025-12-01T10:30:45Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "ai_analysis": {
    "summary": "预计条件良好。东北风轻风，风速 8-12 节，海浪平静，浪高 1-2 英尺。",
    "daily_classifications": [
      {
        "date": "2025-12-05",
        "classification": "GO",
        "summary": "全天风力轻柔，海面平静。"
      },
      {
        "date": "2025-12-06",
        "classification": "CAUTION",
        "summary": "天气状况逐步改善，下午时段为最佳出行窗口。"
      }
    ]
  }
}

响应 (200 OK - 处理中):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "progress": {
    "stage": "analyzing",
    "percentage": 65
  }
}

响应 (200 OK - 失败):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "failed",
  "created_at": "2025-12-01T10:30:00Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "error": "处理失败"
}

获取 SpotCasts 列表

GET https://api.sealegs.ai/v3/spotcasts

获取您账户下的所有 SpotCast。

查询参数：

• limit (整数)：返回结果数量，范围 1-100（默认值：20）
• after (字符串)：分页游标

示例请求：

curl "https://api.sealegs.ai/v3/spotcasts?limit=10" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (200 OK):

{
  "data": [
    {
      "id": "spc_abc123xyz",
      "created_at": "2025-12-01T10:30:00Z",
      "coordinates": {
        "latitude": 25.7617,
        "longitude": -80.1918
      },
      "start_date": "2025-12-05T00:00:00-05:00",
      "end_date": "2025-12-06T23:59:59-05:00",
      "num_days": 2,
      "latest_forecast": {
        "forecast_id": "fcst_xyz789",
        "status": "completed"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "spc_def456"
}

账户

获取余额

GET https://api.sealegs.ai/v3/account/balance

返回您的当前信用余额和使用情况。

示例请求：

curl https://api.sealegs.ai/v3/account/balance \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

响应 (200 OK):

{
  "credit_balance": 100,
  "total_credits_purchased": 200,
  "total_credits_used": 100,
  "purchase_url": "https://developers.sealegs.ai/dashboard/billing"
}

Webhooks

当您在创建或刷新 SpotCast 时提供 webhook_url，SeaLegs 会在处理完成或失败时向该 URL 发送 POST 请求。

Webhook 请求头

Content-Type: application/json
X-SeaLegs-Event: spotcast.forecast.completed
X-SeaLegs-Signature: sha256=abc123...
X-SeaLegs-Delivery-ID: whk_abc123xyz
X-SeaLegs-Timestamp: 1733045400
User-Agent: SeaLegs-Webhooks/1.0

签名验证

每个 webhook 请求均包含一个 HMAC-SHA256 签名，位于 X-SeaLegs-Signature 请求头中。您的 webhook 秘钥可在开发者控制台中获取。在处理请求内容前，请始终验证签名。

Python:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

JavaScript:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

处理完成事件

{
  "event": "spotcast.forecast.completed",
  "created_at": "2025-12-01T10:30:45Z",
  "data": {
    "spotcast_id": "spc_abc123xyz",
    "forecast_id": "fcst_xyz789",
    "status": "completed",
    "summary": "预计条件良好。东北风轻风，风速 8-12 节，海浪平静，浪高 1-2 英尺。",
    "metadata": {
      "trip_name": "周末垂钓行程"
    }
  }
}

summary 字段在 AI 分析成功完成后包含。metadata 对象在原始 POST /v3/spotcast 请求中提供了元数据时返回，内容与发送时完全一致。

处理失败事件

{
  "event": "spotcast.forecast.failed",
  "created_at": "2025-12-01T10:31:00Z",
  "data": {
    "spotcast_id": "spc_abc123xyz",
    "forecast_id": "fcst_xyz789",
    "status": "failed",
    "error": {
      "code": "processing_failed",
      "message": "无法获取指定位置的气象数据"
    },
    "metadata": {
      "trip_name": "周末垂钓行程"
    }
  }
}

重试策略

失败的交付将最多重试 4 次：分别在 5 分钟后、30 分钟后、2 小时后和 24 小时后进行。

错误处理

错误响应格式

{
  "error": {
    "code": "invalid_coordinates",
    "message": "纬度必须在 -90 到 90 之间",
    "param": "latitude"
  }
}

HTTP 状态码

错误代码

认证错误 (401)

授权错误 (403)

付款相关 (402)

验证错误 (400)

未找到资源 (404)

速率限制 (429)

服务器错误 (500)

常见工作流程

获取海洋预报

1. 使用坐标和日期创建 SpotCast
2. 轮询状态端点，直到返回 "completed"
3. 获取包含 AI 分析的完整预报
4. 向用户展示 GO/CAUTION/NO-GO 分类结果

出行前检查天气状况

1. 使用出行坐标和日期创建 SpotCast
2. 包含 vessel_info 以获取定制化建议
3. 检查每日分类结果（daily_classifications）
4. 查看 AI 总结以了解具体风险点

链接

• [开发者门户](https://developer.sealegs.ai)
• [API 文档](https://developer.sealegs.ai/docs/)
• [SeaLegs 应用](https://sealegs.ai)

许可证

MIT