KARDS Decker API

主题

读取卡牌与卡背 ​

卡牌与卡背目录都是公开接口，无需 API Key。

搜索卡牌 ​

GET /api/v1/cards

bash
curl "https://1939.giaory.xyz/api/v1/cards?q=虎式&faction=Germany&pool=active&page=1&limit=20"
参数说明
q在卡牌 ID、导入 ID、中英文名称和描述中搜索
faction按所属或可用阵营筛选
type按卡牌类型筛选
rarity按稀有度筛选
set按扩展包筛选
poolactive、reserve 或 derived
page页码，默认 1
limit每页数量，默认 20，最大 50

pool=reserve 表示搜索官方储备池中的卡牌。它不是某个卡组的“备卡列表”；卡组备卡保存在 guide.reserve_recommendations。

常用返回字段：

字段用途
card_idAPI 中引用卡牌的稳定 ID
import_idKARDS 卡组代码使用的导入 ID
name_zh / name_en中英文名
host_factions可以使用该卡的阵营
poolactive、reserve 或 derived
is_derived是否是衍生卡；衍生卡不能写入备卡
image_url / image_proxy_url卡图地址

按 ID 读取卡牌 ​

GET /api/v1/cards/:card_id

bash
curl "https://1939.giaory.xyz/api/v1/cards/<card_id>"

找不到时返回 404 card_not_found。

搜索卡背 ​

GET /api/v1/card-backs

bash
curl "https://1939.giaory.xyz/api/v1/card-backs?q=德国&limit=20"

卡背条目包含：

json
{
  "id": "<card_back_id>",
  "name": "<卡背名称>",
  "image_url": "https://..."
}

把返回的 id 原样作为创建或更新卡组时的 card_back_id。服务端还会校验卡背是否允许自定义，以及是否符合卡组阵营。

三个容易混淆的字段

  • pool=reserve：官方储备池筛选条件。
  • guide.reserve_recommendations：某个卡组攻略里的备卡 ID 数组。
  • card_back_id：卡组展示使用的卡背资源 ID。