Cards Realm API

快速开始

一个只读的 JSON API，数据与网站本身相同：卡牌、套牌、赛事和选手战绩。

无需 API 密钥。 所有接口均为公开，无需认证、令牌或注册。

GET 或 POST 均可，参数可以放在查询字符串里，也可以放在请求体里。 参见下方的“发送参数”。

基础地址

https://cardsrealm.com/zh-cn/api/

语言段是路径的一部分，决定卡牌名称及其他译文的语言。网站支持的任何 locale 都可以使用。

选择游戏。 两种方式，效果相同：调用该游戏自己的子域名，或传入 game_id 参数。两者都不用时，返回你所调用域名对应的游戏。

请求示例

curl "https://cardsrealm.com/en-us/api/getRecentDecks?game_id=1&limit=2"

价格是以分为单位的整数。 price 为 77、currency_prefix 为 $ 表示 0.77。显示前请除以 100。

合理使用。 目前没有强制的请求频率限制，所以请自觉：能缓存就缓存，并优先使用一次分页请求而不是许多次小请求。滥用会让开放的 API 变成封闭的。

发送参数

每个端点都同时响应 GET 和 POST，并从下列任一种方式中读取参数，哪种方便就用哪种。响应完全相同。

发送方式	`Content-Type`
查询字符串（GET 或 POST）	—
简单表单	`application/x-www-form-urlencoded`
多部分表单	`multipart/form-data`
JSON	`application/json`

同一个调用，三种写法

curl "https://cardsrealm.com/zh-cn/api/getRecentDecks?game_id=1&limit=2"

curl -X POST "https://cardsrealm.com/zh-cn/api/getRecentDecks" \
     -d "game_id=1" -d "limit=2"

curl -X POST "https://cardsrealm.com/zh-cn/api/getRecentDecks" \
     -H "Content-Type: application/json" \
     -d '{"game_id": 1, "limit": 2}'

数字可以就是数字。 在表单里所有值都以文本到达；用 JSON 时可以直接发送 1 而不是 "1"。两种都能用。

不要手动设置 Content-Type 头 在 Postman、Insomnia 或 HTTP 库里都是如此。让工具自己生成：multipart 需要带上 boundary，而与请求体不匹配的 Content-Type 会让所有字段都变成空。这时返回的 400 说的是信封，不是你的字段：

响应

{
  "error": "无法读取请求体中的字段。请以 form-data、x-www-form-urlencoded 或 JSON 发送。",
  "hint": "如果你用 Postman 或 Insomnia，请删掉 Content-Type 头，让工具自己生成。"
}

可以从浏览器调用。 你自己域名下的页面可以直接从浏览器调用它。不读取任何 cookie 或凭据。

cardinfo

GET/zh-cn/api/cardinfo

按名称查找一张卡牌的全部信息：规则文本、法术力费用、稀有度、版本与当前价格。

参数	类型	图案	笔记
`cardname`	string	`Path to exile`	最多 50 个字符。
`currency`	string	该 locale 的货币	三个字母。
`game_id`	int	该域名对应的游戏	1 = Magic, 2 = Yu-Gi-Oh, 3 = Pokémon, 4 = Runeterra.
`language_code`	string	路径中的语言	返回的卡牌名称与文本所用的语言。

请求示例

curl "https://cardsrealm.com/zh-cn/api/cardinfo?cardname=Lightning%20Bolt&currency=USD"

响应示例

{
  "name_of_card": "Lightning Bolt",
  "name_ing": "Lightning Bolt",
  "type_of_card": "Instant",
  "text_of_card": "Lightning Bolt deals 3 damage to any target.",
  "price": 77,
  "currency_prefix": "$",
  "path_of_card": "oj7-lightning-bolt",
  "card_url": "https://mtg.cardsrealm.com/en-us/card/lightning-bolt"
}

getCardsInfo

GET/zh-cn/api/getCardsInfo

一次调用返回多张卡牌的名称、图片、背面和类型。就是 cardinfo 的内容，去掉价格和版本，一次覆盖整份套牌列表。

参数	类型	图案	笔记
`cards`	string	必需的	用 \| 分隔的英文卡牌名称。最多 250 个名称，每个最多 100 个字符。不传时接口返回 400。
`game_id`	int	该域名对应的游戏	与 cardinfo 相同。
`language_code`	string	路径中的语言	返回的卡牌名称和图片所用的语言。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getCardsInfo?cards=Lightning%20Bolt%7CSol%20Ring"

响应示例

[
  {
    "name_ing": "Lightning Bolt",
    "name_of_card": "Lightning Bolt",
    "image_of_card": "https://cdn.cardsrealm.com/images/cartas/clu-ravnica-clue-edition/EN/med/lightning-bolt-141.png?5541",
    "back_of_card": "",
    "type_of_card": "Instant"
  },
  {
    "name_ing": "Sol Ring",
    "name_of_card": "Sol Ring",
    "image_of_card": "https://cdn.cardsrealm.com/images/cartas/sld-secret-lair-drop/EN/med/sol-ring-2063.png?7315",
    "back_of_card": "",
    "type_of_card": "Artifact"
  }
]

站点不认识的名称不会出现在结果里：把发送的列表和返回的列表对比即可。

getCardsRelated

GET/zh-cn/api/getCardsRelated

一组卡牌会带上场的卡牌：它们创造的衍生物、标记，以及它们召唤的牌。适合手里有一份牌表、需要知道这副套牌用到哪些衍生物的人——整副套牌只要调用一次。

参数	类型	图案	笔记
`cards`	string	必需的	用 \| 分隔的英文卡牌名称。最多 250 个名称，每个最多 100 个字符。不传时接口返回 400。
`game_id`	int	该域名对应的游戏	与 cardinfo 相同。
`language_code`	string	路径中的语言	返回的卡牌名称与文本所用的语言。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getCardsRelated?cards=Young%20Pyromancer%7CLingering%20Souls"

响应示例

[
  {
    "card_id": 20194,
    "name_of_card": "Elemental Token",
    "name_ing": "Elemental Token",
    "image_of_card": "https://cdn.cardsrealm.com/images/cartas/tdsc-duskmourn-commander-tokens/EN/med/elemental-token-9.png?1457",
    "back_of_card": "https://cdn.cardsrealm.com/images/cartas/tust-unstable-tokens/en/back/elemental-token-11.png?3508",
    "type_of_card": "Token creature — elemental",
    "set_name": "Duskmourn: House of Horror Commander Tokens",
    "related_to": "Young Pyromancer"
  }
]

related_to 列出你所提交的名单中会把它放上场的卡牌，用 " | " 分隔。由套牌中两张牌创造的同一个衍生物只返回一次，并附上两张牌的名称。

衍生物使用创造它的那张卡牌的版本，image_of_card 就是该版本的图片：当列表中不同的卡牌创造同一衍生物的不同版本时，同一衍生物名称可能以不同卡图返回多次。在多个系列中重印过的卡牌返回其最新版本。

getCardArts

GET/zh-cn/api/getCardArts

一张卡牌的所有画版（印刷版本），最新的排在最前：与卡牌页面显示的系列列表相同，但这里是按名称查询，而不是按 card_id。适用于手上只有一份套牌列表的场景，例如 play.cardsrealm.com 的对战桌，玩家可以在对局中更换卡牌的画版。

参数	类型	图案	笔记
`cardname`	string	必需的	卡牌名称，可用英文或 language_code 指定的语言。最多 100 个字符。缺少该参数时请求返回 400。
`game_id`	int	该域名对应的游戏	与 cardinfo 相同。
`language_code`	string	路径中的语言	返回的卡牌名称和图片所用的语言。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getCardArts?cardname=Lightning%20Bolt"

响应示例

[
  {
    "card_set_id": 9525351,
    "print_name": "Secret Lair Drop",
    "set_rarity": 2,
    "set_number": "2579",
    "set_artist": "Jessica Fong",
    "name_ing": "Lightning Bolt",
    "name_of_card": "Lightning Bolt",
    "image_of_card": "https://cdn.cardsrealm.com/images/cartas/sld-secret-lair-drop/EN/med/lightning-bolt-2579.png?2214",
    "back_of_card": ""
  }
]

响应是一个最多包含 120 条印刷版本的列表，从最新排到最旧。单面卡牌的 back_of_card 为空。

getDeckByPath

GET/zh-cn/api/getDeckByPath/<deck_path>

与 getDeckByID 相同的套牌，通过链接里的路径查找，适合只有链接而没有 id 的情况。

参数	类型	图案	笔记
`deck_path`	string	必需的	放在 URL 里，而不是查询字符串。就是链接中 /decks/ 之后的部分：mkh-sidar。
`currency`	string	`BRL`	三个字母。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getDeckByPath/mkh-sidar"

返回内容与 getDeckByID 相同；没有套牌匹配该路径时返回 404。

getRecentDecks

GET/zh-cn/api/getRecentDecks

最近发布的套牌，最新在前。

参数	类型	图案	笔记
`page`	int	`1`	页码。
`limit`	int	`50`	每页套牌数。上限为 500，超过则返回错误。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getRecentDecks?page=1&limit=2"

响应示例

[
  {
    "deck_id": 374859,
    "deck_title": "Attack of the myrs",
    "deck_owner": "jarrod long",
    "deck_format_name": "Commander",
    "deck_colours": "B G R U W",
    "total_cards": 100,
    "deck_url": "https://cardsrealm.com/decks/en-us/l8dh-attack-of-the-myrs"
  }
]

getDeckByID

GET/zh-cn/api/getDeckByID

完整的套牌列表。卡牌清单位于 cards 字段，包含数量、board（main 或 side）以及每张卡的价格。

参数	类型	图案	笔记
`deck_id`	int	`0`	套牌的数字 id。
`currency`	string	`BRL`	三个字母。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getDeckByID?deck_id=374859&currency=USD"

响应示例

{
  "deck_title": "Attack of the myrs",
  "user_name": "jarrod long",
  "tour_type_name": "Commander",
  "deck_quantity_main": 99,
  "deck_quantity_side": 1,
  "cards": [
    {
      "name_ing": "Command Tower",
      "deck_quantity": 1,
      "deck_sideboard": 0,
      "card_price_total": 18
    }
  ]
}

不存在的 deck_id 会返回 200 和一个近乎空的对象，而不是错误。使用其余字段前请先确认 deck_title 是否存在。

getDeckResults

GET/zh-cn/api/getDeckResults

某个套牌原型的表现：总体战绩，并按 by_meta 细分它对阵其他每个原型的结果。

参数	类型	图案	笔记
`deck_name`	string	空	套牌原型名称，最多 40 个字符。
`week`	int	`4`	回溯多少周。上限为 52。
`format`	string	`Standard`	最多 20 个字符。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getDeckResults?deck_name=Grixis%20Affinity&format=Pauper&week=8"

getPlayerResults

GET/zh-cn/api/getPlayerResults

某位玩家的战绩，并按 by_meta 细分他在每个套牌原型下的表现。

参数	类型	图案	笔记
`player_name`	string	空	最多 40 个字符。
`week`	int	`52`	回溯多少周。
`player_platform`	string	`cardsrealm_nickname`	按哪个名称检索。取 cardsrealm_nickname、mtgo、arena、riot 或 display 之一。其他取值将返回错误。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getPlayerResults?player_name=Carrubs&player_platform=mtgo"

getPastTournaments

GET/zh-cn/api/getPastTournaments

已经举办过的赛事，最新在前。

参数	类型	图案	笔记
`page`	int	`1`	页码。
`format`	string	空	最多 20 个字符。留空表示所有赛制。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getPastTournaments?format=Pauper&page=1"

响应示例

[
  {
    "tournament_id": 810845,
    "tournament_name": "Domingooouuu Pauper 86",
    "tournament_path": "https://cardsrealm.com/tournament/en-us/1k3c9-domingooouuu-pauper-86",
    "format_name": "Pauper",
    "game_name": "Magic: the Gathering",
    "datetime_utc": "Sun, 16 Aug 2026 16:30:00 GMT"
  }
]

getTournamentInfo

GET/zh-cn/api/getTournamentInfo

一场赛事的完整信息：赛事本身、位于 round_info 的各轮次，以及位于 standings 的最终排名。不存在的 id 返回空列表，而非错误。

参数	类型	图案	笔记
`tournament_id`	int	`1`	赛事的数字 id。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getTournamentInfo?tournament_id=810845"

getUserTournaments

GET/zh-cn/api/getUserTournaments

由某个账号举办的赛事。

参数	类型	图案	笔记
`nickname`	string	`Cards Realm`	最多 30 个字符。

请求示例

curl "https://cardsrealm.com/zh-cn/api/getUserTournaments?nickname=leon-diniz"

错误与支持

代码	意义
`200`	成功。响应体始终为 JSON。
`400`	调用被拒绝：名称太长、数字不是数字、取值不在允许的列表内，或请求体无法读取。
`500`	是我们这边出了问题。欢迎告诉我们。

被拒绝的调用返回 400 和一个对象。invalid_fields 指出值得检查的参数；当问题不在某个具体字段时，它不会出现。

响应

{
  "error": "周必须是数字",
  "invalid_fields": ["week"]
}

这一点在 2026 年 9 月 8 日发生了变化。 以前被拒绝的调用返回 404 和一个裸字符串。消息内容不变，变的是状态码和外层结构。变更日志

有疑问，或者需要这里没有的字段？来 Discord 找我们。 Discord