KARDS 军械库 API

基于 Node.js + Canvas 的 KARDS 卡组图片生成服务，由KARDS 军械库提供。

声明

本项目遵循1939 Games的 "Community content policy"(社区内容政策) ，使用1939 Games 拥有的资产。1939 Games 并未直接支持或赞助本项目。所有卡牌图像版权归 1939 Games 所有，本项目仅作非商业学习与工具用途。

部署

Render 一键部署

点击下方按钮部署到 Render：

手动部署

1. 克隆仓库
2. 安装依赖：

npm install

3. 启动服务：

npm start

环境要求

• Node.js 18.x

• 系统依赖:

  • libcairo2-dev

  • libjpeg-dev

  • libpango1.0-dev

  • libgif-dev

  • build-essential

  • libvips-dev(Weserv版不需要)

API

接口

https://kapi-v7wl.onrender.com/generate

生成卡组图片

端点： POST /generate

请求头

Content-Type: application/json

请求体

基础

参数	类型	默认值	描述
deckCode	string	-	必填，KARDS卡组代码
cols	number	10	每行卡牌数量
scale	number	100	缩放比例(25-100)
lang	string	zh-Hans	语言代码
bgColor	string	transparent	背景颜色(十六进制颜色码)

附件

参数	类型	默认值	描述
foldEnabled	boolean	false	折叠重复卡牌
addStatsCard	boolean	true	统计卡
statsTitle	string	卡组统计	统计卡标题
qrEnabled	boolean	false	二维码卡
qrTitle	string	卡组二维码	二维码卡标题
hq	string	-	总部cardId(如moscow)
statsChartToggle	boolean	false	额外统计图

高级

参数	类型	默认值	描述
version	string	DEFAULT_VERSION	卡牌版本
spacingX	number	0	水平间距
spacingY	number	0	垂直间距
emptySlots	array	[]	空位索引数组
cardOverrides	object	{}	单卡覆盖配置

cardOverrides 格式：

{
  "cardId": {
    "version": "v52",
    "cost": 3,
    "star": true
  }
}

语言代码

代码	语言
zh-Hans	简体中文
zh-Hant	繁体中文
en-EN	English
fr-FR	Français
de-DE	Deutsch
pl-PL	Polski
pt-BR	Português
ru-RU	Pусский
it-IT	Italiano
es-ES	Español
ko-KR	한국어
ja-JP	日本語

响应格式

{
  "mainImage": "data:image/png;base64,...",
  "statsChart": "data:image/png;base64,..."
}

字段	描述
mainImage	卡组图片(Base64)
statsChart	额外统计图(仅当 statsChartToggle: true 时返回)

错误响应

{
  "error": "错误描述"
}

示例

cURL

curl -X POST https://your-service.onrender.com/generate \
  -H "Content-Type: application/json" \
  -d '{
    "deckCode": "%%15|;;bK;bKbKbKbKbKbKbKbKbK",
    "cols": 8,
    "lang": "zh-Hans"
  }'

JavaScript (Node.js)

import fs from 'fs';

const response = await fetch('https://your-service.onrender.com/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    deckCode: '%%15|;;bK;bKbKbKbKbKbKbKbKbK',
    cols: 8,
    lang: 'zh-Hans'
  })
});

const data = await response.json();
// 提取 Base64 数据
const base64Data = data.mainImage.replace(/^data:image\/png;base64,/, '');
fs.writeFileSync('deck.png', Buffer.from(base64Data, 'base64'));

Python

import requests
import base64

response = requests.post('https://your-service.onrender.com/generate', json={
    'deckCode': '%%15|;;bK;bKbKbKbKbKbKbKbKbK',
    'cols': 8,
    'lang': 'zh-Hans'
})

data = response.json()
base64_data = data['mainImage'].split(',')[1]
with open('deck.png', 'wb') as f:
    f.write(base64.b64decode(base64_data))

文件结构

├── server.js          # 服务入口
├── deckRenderer.js    # 核心渲染逻辑
├── cardData.js        # 卡牌数据加载
├── package.json       # 项目配置
├── render.yaml        # Render 部署配置
├── font.ttf           # 中文字体文件
├── data.json          # 卡牌数据库
├── germany.svg        # 阵营图标
├── britain.svg
└── ...

跨域Weserv代理版

使用wsrv.nl代理卡图避免跨域问题，如果服务器在国内。

文件替换

使用weserv目录下的文件替换：

├── deckRenderer.js
├── package.json
└── render.yaml

额外参数

参数	类型	默认值	描述
quality	number	20	图片质量(1-100)

控制Weserv的画质参数

注意事项

1. 卡牌数据：需同步更新data.json
2. 阵营图标：{faction}.svg 文件
3. 部署环境：本API使用 Render 免费计划，启动速度快如故障机器人

许可

MIT