HeXi/hexi/plugins/nonebot_plugin_helldivers_tools/doc/api.md

Helldivers 自部署 API 说明

本文档基于对自部署实例 http://192.168.2.15:18080 的实际探测整理（字段以真实返回为准）。 用途：弄清这个代理能拿到哪些数据，以及战报卡片还没利用的部分。

---

0. 基础信息

Base URL：http://192.168.2.15:18080

请求头（两个 X-Super-* 必须都带，否则公共实例会直接 400）：

Accept-Language: en-US,zh-Hans;q=0.5
X-Super-Client: <你的客户端名>
X-Super-Contact: <联系方式>

• Accept-Language 决定返回文案语言（en-US / zh-Hans/zh-Hant 等）。
• 返回均为 JSON。

注意（坑）：

• /api/v1/war 的 now 返回 1972-...，疑似该代理的数据有误（started/ended 是 2024→2028 也偏大）。用真实时间请自己取 time.time()，别信 war.now。
• /api/v1/planet-events 返回的是单颗星球对象（数组里只有 index 130），不是事件列表——疑似别名或代理异常。真正的星球事件在 /raw/.../Status 的 planetEvents。
• 接口返回可能被外层包裹成 {data:[...]} 或 {planets:[...]}，/api/v1/* 目前探测到是裸数组/裸对象。

---

1. 接口总览

端点	形状	说明
GET /api/v1/war	object	星系战况概要
GET /api/v1/assignments	array[1]	重要指令（最高指令 MAJOR ORDER）
GET /api/v1/campaigns	array[35]	当前战役（参战星球）
GET /api/v1/planets	array[273]	全星球表
GET /api/v1/planets/{index}	object	单星球详细情况
GET /raw/api/WarSeason/801/Status	object	原始战争状态（最全）

以下 /api/v1/* 均 404：attacks、galaxy、galaxy-war、global-events、news、statistics、space-stations、space_stations、war/status、war/statistics、war/summary、planet-effects、steam/war、version。 /raw/api/WarSeason/801/* 只有 Status 可用（Planets、Assignments、Campaigns、News、Statistics、GlobalEvents、SuperEarthWarResults、Planets/224、Planet/224/Statistics 均 404）。

---

2. 各端点字段详解

2.1 GET /api/v1/war — 星系战况概要

{
  "started": "2024-01-23T20:05:13Z",
  "ended": "2028-02-08T20:04:55Z",
  "now": "1972-07-14T16:19:50Z",
  "clientVersion": "0.3.0",
  "factions": ["Humans", "Terminids", "Automaton", "Illuminate"],
  "impactMultiplier": 0.019517466,
  "statistics": {
    "missionsWon": 1011049334, "missionsLost": 98505230, "missionTime": 3325809094530,
    "terminidKills": 216600333572, "automatonKills": 114998420419, "illuminateKills": 75823458605,
    "bulletsFired": 1944890521255, "bulletsHit": 2131033542437, "timePlayed": 3325809094530,
    "deaths": 8728394343, "revives": 2, "friendlies": 1009517116,
    "missionSuccessRate": 91, "accuracy": 100, "playerCount": 57302
  }
}

字段	说明
factions	参战阵营英文名（Humans/Terminids/Automaton/Illuminate）
impactMultiplier	全局影响倍数
statistics	全局累计统计（任务/击杀/子弹/命中/死亡/胜率/命中率/玩家数）

可自定义用途：顶部全局统计、累计击杀对比、胜利/失败率。

2.2 GET /api/v1/assignments — 重要指令（最高指令）

{
  "id": 3348823937,
  "progress": [1, 0, 0],
  "title": "MAJOR ORDER",
  "briefing": "Liberate the designated enemy planets, ...",
  "description": null,
  "tasks": [
    { "type": 11, "values": [1, 1, 171], "valueTypes": [3, 11, 12] },
    { "type": 11, "values": [1, 1, 172], "valueTypes": [3, 11, 12] },
    { "type": 11, "values": [1, 1, 268], "valueTypes": [3, 11, 12] }
  ],
  "reward": { "type": 1, "amount": 50 },
  "rewards": [ { "type": 1, "amount": 50 } ],
  "expiration": "2026-08-31T12:03:32.7346799Z",
  "flags": 0
}

字段	说明
title	指令名（MAJOR ORDER / 玩家自定义战役等）
briefing	指令说明文本（英文）
progress	各目标进度（与 tasks 对位）
tasks[].type	任务类型（11 = 解放/进攻某星球类）
tasks[].values	与 valueTypes 对位：如 [1,1,171]，其中 171/172/268 为目标星球 index
tasks[].valueTypes	各 values 的含义（3 疑似星球 index，11/12 为计数类；需再对照官方定义）
reward / rewards	奖励：type(1=奖章/2=征用券/3=超级货币/4=补助/5=经验) + amount
expiration	指令截止时间

说明：战报卡片的「重要指令」已用 title/briefing/expiration；progress/tasks/rewards 目前基本没用上，可用来做进度条（解放了 1/3 颗目标星）和奖励展示。

2.3 GET /api/v1/campaigns — 当前战役（参战星球）

{
  "id": 51413,
  "type": 0,
  "count": 10,
  "faction": "Humans",
  "planet": {
    "index": 7, "name": "...", "sector": "...",
    "biome": { "name": "...", "description": "..." },
    "hazards": [ { "name": "Tremors", "description": "..." } ],
    "maxHealth": ..., "health": ..., "regenPerSecond": ...,
    "currentOwner": "...", "initialOwner": "...",
    "event": null,
    "statistics": { ... }, "attacking": [], "regions": []
  }
}

字段	说明
faction	战役阵营（Humans/Terminids/Automaton/Illuminate）。解放战=当前占据的敌方；防守战=进攻的敌方
type	战役类型（0 = 解放/常规；campaign.type 1 可能 = 防守）
count	战役数量（参与该星球的战役条目数，通常为 1）
planet	完整星球对象（同 /api/v1/planets/{index}，含 biome/hazards/event/statistics/attacking/regions）

可自定义用途：faction 决定阵营色、type 区分解放/防守、planet.hazards 是危害来源（卡片已用）、planet.event 是侵攻事件。

2.4 GET /api/v1/planets / GET /api/v1/planets/{index} — 星球

{
  "index": 224, "name": "RD-4", "sector": "Orion",
  "biome": { "name": "Moon", "description": "...", "icon": "..." },
  "hazards": [ { "name": "Meteor Storms", "description": "...", "icon": "..." } ],
  "hash": 1234567890,
  "position": { "x": 0.29, "y": -0.87 },
  "waypoints": [],
  "maxHealth": 1000000, "health": 1000000,
  "disabled": false, "initialOwner": "Illuminate", "currentOwner": "Illuminate",
  "regenPerSecond": 1.1111112,
  "event": null,
  "statistics": {
    "missionsWon": 1290109, "missionsLost": 152477, "missionTime": 4488281762,
    "terminidKills": 1344, "automatonKills": 3656, "illuminateKills": 604567039,
    "bulletsFired": 3286403648, "bulletsHit": 3218310824, "timePlayed": 4488281762,
    "deaths": 9153248, "revives": 0, "friendlies": 1324721,
    "missionSuccessRate": 89, "accuracy": 97, "playerCount": 71
  },
  "attacking": [],
  "regions": []
}

字段	说明
index / name	星球编号 / 英文名
sector	星区英文名（战报里显示中文分区名）
biome	地形（英文名 + 描述；_translate 加 i18n→中文）
hazards[]	气象危害（每颗星一个数组，可能多个；name 为英文，加 i18n→中文）
maxHealth/health/regenPerSecond	战役血量 / 现值 / 回复速度（解放进度 = (max-health)/max）
currentOwner/initialOwner	当前/初始阵营（英文名）
event	进攻事件（空则无）
statistics	星球累计统计（击杀/胜率/命中率/玩家数）
attacking	正在进攻的条目（当前数据为空数组）
regions	行星区域权属（当前为空数组）

提示：hazards 才是「环境事件」，且一个星球可出现多个；战报卡片的「环境事件」槽位已支持多危害图标+名称展示。

2.5 GET /raw/api/WarSeason/801/Status — 原始战争状态（最全）

顶层键：warId, time, impactMultiplier, storyBeatId32, planetStatus, planetAttacks, campaigns, communityTargets, jointOperations, planetEvents, planetActiveEffects, planetRegions, activeElectionPolicyEffects, globalEvents, superEarthWarResults, spaceStations, layoutVersion

子数组	形状	样例 / 字段
planetStatus [273]	{index, owner, health, regenPerSecond, players, position:{x,y}}	每颗星实时状态（比 /api/v1/planets 更轻、更新）
planetAttacks [50]	{source, target}	进攻路线（source 星 → target 星）
campaigns [35]	{id, planetIndex, type, count, race}	战役（race 数字阵营、type 0/1）
planetEvents [1]	{id, planetIndex, eventType, race, health, maxHealth, startTime, expireTime, campaignId, jointOperationIds, potentialBuildUp}	被攻星球的进攻事件（最完整：含 maxHealth / expireTime / 联合作战）
planetActiveEffects [154]	{index, galacticEffectId}	星球生效效果（galacticEffectId → 效果图标）
planetRegions [40]	{planetIndex, regionIndex, owner, health, regerPerSecond, availabilityFactor, isAvailable, players}	行星区域权属/血量/玩家（可做区域细览）
spaceStations [1]	{id32, planetIndex, activeEffectIds[], currentElectionEndWarTime, flags}	空间站（DSS）：所在星 + 生效效果列表
jointOperations [1]	{id, planetIndex, hqNodeIndex}	联合作战节点
globalEvents [2]	{eventId, id32, portraitId32, title, titleId32, message, ...}	战争级事件公告（战役成功等）
communityTargets	[]（空）	社区目标（当前无）
activeElectionPolicyEffects	[]（空）	选举政策效果（当前无）
superEarthWarResults	[]（空）	战争结果（当前无）

说明：planetStatus[].owner 是数字阵营（0=人类/1=终结族/2=机器人/3=光能族 之类），与 /api/v1/planets 的英文字符串阵营对应关系需要你确认——原生 HD2 里 owner 数字：1=Humans, 2=Terminids, 3=Automaton, 4=Illuminate。

---

3. 战报卡片：已用 / 未利用

已利用

• war → 顶部标题信息
• assignments → 重要指令（title/briefing/expiration）
• campaigns[].planet → 战役卡片（进度/危害/地形/效果）
• planets（en-US 星名）→ 匹配高清地形背景
• raw.planetActiveEffects → planet_effects（星球效果槽位）
• raw.spaceStations → space_stations（DSS 增益）

还有可利用（建议关注）

数据	来源	可做什么
planetEvents（maxHealth/expireTime）	/raw/Status	更准的入侵进度 + 倒计时（目前卡片从 campaign.planet.event 取，缺 maxHealth/expireTime 时精度差）
planetAttacks（source→target）	/raw/Status	战线图/进攻箭头：可视化谁正在打谁
planetRegions	/raw/Status	星球区域占领细览（每区域 owner/health/players）
globalEvents	/raw/Status	战报滚动公告（战役成功/事件推送）
planetStatus[].owner/regen/players	/raw/Status	全星系战况概览（比全量星球更轻）
planet.statistics	/api/v1/planets/{i}	星球数据卡（击杀/胜率/命中率/玩家数）
war.statistics	/api/v1/war	顶部全局累计统计
assignment.progress/tasks/rewards	/api/v1/assignments	重要指令进度条（解放了几颗目标星）+ 奖励展示

---

4. 状态码 / 异常

• 200：正常（返回 JSON）。
• 400：缺 X-Super-Client / X-Super-Contact（或头格式错误）。
• 404：接口不存在（见上表 404 清单）。
• 某些异常时可能返回 JSON {error: ...} 或带 Message 字段；建议调用方对非 200 抛出带 resp.text[:400] 的错误（hd2_api._get_json 已如此处理）。