前言

在开发棋牌游戏助手、英雄战力监控或社交平台播报机器人时，获取王者荣耀英雄在全国各区服的战力分布是一项常见需求。本文围绕王者荣耀全国战力查询 API，详细拆解其请求参数、鉴权方式、响应字段，并结合工程化场景给出接入建议。

接口能力与适用场景

该接口使用 GET 方式调用，基础地址为https://v1.apizero.cn/api/wzry，单接口整合两大功能：

• 英雄列表查询：获取全部 130+ 英雄的ename（数字标识）、name（中文名）、title（称号）以及头像 URL。
• 战力分布查询：针对指定英雄在指定区服（Android QQ、Android 微信、iOS QQ、iOS 微信），返回省级、市级、区级三个层级的战力排名数据，并附带近似的全国排名。

典型使用场景：

• 工具类应用：展示某英雄当前省级最低上榜战力。
• 数据看板：按区服统计热门英雄的准入分数线。
• Bot 消息：用户输入“赵云 安卓QQ 最低战力”后自动查询并回复。

请求方式与鉴权

请求方法

GET

HTTP Header

若需要更高调用频率，请将 API Key 附在请求头中：

-H "Authorization: Bearer sk_live_your_key"

请求参数详解

Query 参数总表

参数组合逻辑

• 英雄列表模式：只需action=heroes，无需传递 hero/zone/type。
• 战力查询模式：action=query必须同时提供英雄标识（hero或hero_id）和区服zone。若同时传入hero和hero_id，接口优先使用hero_id。
• type 默认值：若不传type，默认返回all，即完整的约 90 条省市区战力数据；min和max仅返回各级最高或最低的那一条，并附带相近排名（rank ≤ +100）。

curl 示例

获取英雄列表

curl -sS -X GET "https://v1.apizero.cn/api/wzry?action=heroes" | jq .

无鉴权时直接调用即可（每日有限额），返回一个包含code: 0的 JSON 数组，其中data字段为英雄对象列表。

查询赵云在 Android QQ 区的最低战力

curl -sS -X GET \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxx" \ "https://v1.apizero.cn/api/wzry?action=query&hero=%E8%B5%B5%E4%BA%91&zone=aqq&type=min"

注意：hero参数需进行 URL 编码（中文→%E8%B5%B5%E4%BA%91）。若使用hero_id可直接传数字，无需编码：&hero_id=107。

查询指定英雄的完整战力分布（all 类型）

curl -sS -X GET \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxx" \ "https://v1.apizero.cn/api/wzry?action=query&hero_id=107&zone=iwx&type=all"

响应结构解读

成功时返回格式如下（以type=min为例）：

{ "code": 0, "msg": "成功", "data": { "action": "query", "hero": { "avatar": "https://game.gtimg.cn/images/yxzj/img201606/heroimg/107/107.jpg", "ename": "107", "name": "赵云", "title": "苍天翔龙" }, "rank_data": { "extreme": { "province": { "adcode": "...", "address": "云南", "level": "province", "rank": 4500 }, "city": { "adcode": "...", "address": "海南/三亚市", "level": "city", "rank": 1800 }, "district": { "adcode": "...", "address": "北京/朝阳区", "level": "district", "rank": 800 } }, "similar": { "province": [ { "address": "云南", "rank": 4500 }, { "address": "甘肃", "rank": 4520 } ], "city": [], "district": [] } }, "syn_date": "2026-05-06", "type": "最低战力", "type_code": "min", "zone": { "code": "aqq", "platform": "QQ", "system": "Android" } }, "request_id": "abc123def456" }

字段说明

• data.hero：包含英雄的基本信息，avatar为游戏官方面向资源链接，可用于展示。
• data.rank_data.extreme：极端值（最高或最低）战力对象，包含province、city、district三级，每级包含地址和战力数值（rank）。
  • address格式为“省名”或“省/市名”或“市/区名”。
  • rank即为该层级对应的上榜战力。
• data.rank_data.similar：与 extreme 中同级的相近排名列表（type=min时表示低于当前值的其他省份/城市/区）。type=max时则为高于当前值的其他区域。
• data.syn_date：数据同步时间，格式YYYY-MM-DD。
• data.type与data.type_code：对应请求的type参数。
• data.zone：区服信息。

当type=all时，extreme字段不再体现，而是直接返回一个完整的list数组（包含省市区混合排序的约 90 条记录）。

错误处理与常见问题

建议调用方在代码中判断code是否为 0，非零时读取msg进行展示或记录request_id用于排查。

最佳实践与工程化注意事项

1. 缓存英雄列表

英雄列表数据相对固定（仅在游戏版本更新时变动），建议：

• 首次启动时调用action=heroes获取并本地缓存（如 Redis 或本地 JSON）。
• 设置合适的 TTL（如 24 小时），或监听游戏版本公告手动刷新。
• 前端展示时可预置常用英雄的 ename，减少接口开销。

2. 参数校验前置

在发起请求前，对参数做完整性检查：

VALID_ZONES = ['aqq', 'awx', 'iqq', 'iwx'] VALID_ACTIONS = ['heroes', 'query'] def validate_query_params(action, hero, hero_id, zone): if action not in VALID_ACTIONS: raise ValueError("action must be heroes or query") if action == 'query': if not zone or zone not in VALID_ZONES: raise ValueError("Invalid zone for query action") if not hero and not hero_id: raise ValueError("Must provide hero or hero_id for query")

3. 选择合适的 type

• 若只需要了解上榜门槛（最低战力）或头部战力（最高战力），使用min或max，减少流量消耗。
• 若需要完整的同英雄排名分布（如构建热门战区地图），再用all。

4. QPS 管理与重试

接口 QPS 限制为 5 次/秒，建议：

• 在同步请求场景中使用简单的令牌桶或队列，控制每秒不超过 5 次。
• 对于高并发场景（如批量查询多个英雄），采用异步发送并加入指数退避重试（间隔 200ms→500ms→1s）。

import time import requests def query_with_retry(params, retries=3): for i in range(retries): resp = requests.get(API_URL, params=params, ...) if resp.status_code == 429: wait = 0.2 * (2 ** i) time.sleep(wait) continue return resp return None

5. 数据解析与展示

• address字段用/分隔省、市、区，可拆分用于地图下钻。
• rank值为战力数值，无单位。
• syn_date用于标注数据时效性，建议 UI 中显示“数据截至：2026-05-06”以增加透明度。

6. 注意编码和 Content-Type

• 请求参数中的中文必须进行 URL 编码（如hero=赵云应编码为hero=%E8%B5%B5%E4%BA%91）。
• 响应 Header 中Content-Type: application/json，解析时使用 UTF-8 解码。

参考文档

• 王者战力查询接口官方文档
• 原始 Markdown 文档
• 英雄 JSON 源