王者荣耀战力查询接口：参数深度解析与高效使用技巧
前言
在开发棋牌游戏助手、英雄战力监控或社交平台播报机器人时，获取王者荣耀英雄在全国各区服的战力分布是一项常见需求。本文围绕王者荣耀全国战力查询 API，详细拆解其请求参数、鉴权方式、响应字段，并结合工程化场景给出接入建议。
接口能力与适用场景
该接口使用 GET 方式调用，基础地址为https://v1.apizero.cn/api/wzry，单接口整合两大功能：
- 英雄列表查询：获取全部 130+ 英雄的
ename（数字标识）、name（中文名）、title（称号）以及头像 URL。 - 战力分布查询：针对指定英雄在指定区服（Android QQ、Android 微信、iOS QQ、iOS 微信），返回省级、市级、区级三个层级的战力排名数据，并附带近似的全国排名。
典型使用场景：
- 工具类应用：展示某英雄当前省级最低上榜战力。
- 数据看板：按区服统计热门英雄的准入分数线。
- Bot 消息：用户输入“赵云 安卓QQ 最低战力”后自动查询并回复。
请求方式与鉴权
请求方法
GET
HTTP Header
| 参数名 | 必填 | 说明 |
|---|---|---|
Authorization | 否 | API Key 鉴权，格式Bearer sk_live_xxx。匿名调用时可省略，但有每日 50 次限制。 |
若需要更高调用频率，请将 API Key 附在请求头中：
-H "Authorization: Bearer sk_live_your_key"请求参数详解
Query 参数总表
| 参数 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
action | string | 是 | 操作类型：heroes获取英雄列表；query查询战力分布 | query |
hero | string | 条件必填 | 英雄中文名，与hero_id二选一。当action=query时必选其一。 | 赵云 |
hero_id | number | 条件必填 | 英雄ename数字编号。与hero二选一，且优先级高于hero。 | 107 |
zone | string | 条件必填 | 区服代码：aqq（Android QQ）、awx（Android 微信）、iqq（iOS QQ）、iwx（iOS 微信）。action=query时必填。 | aqq |
type | string | 否 | 返回类型：all（完整列表，默认）、min（各级最低战力+相近排名）、max（各级最高战力+相近排名） | min |
参数组合逻辑
- 英雄列表模式：只需
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 条记录）。
错误处理与常见问题
| 错误场景 | HTTP Status | code | msg 示例 | 处理方法 |
|---|---|---|---|---|
| 缺少必填参数 | 400 | -1 | 参数错误：缺少action | 按文档补全参数 |
| 英雄名不存在 | 200 | 1001 | 英雄“李四”不存在 | 使用英雄列表接口校验名称 |
| 区服代码非法 | 400 | -1 | zone 参数值非法 | 仅允许 aqq/awx/iqq/iwx |
| API Key 无效/额度不足 | 401 | -1 | 认证失败 | 检查 Key 或更换匿名调用 |
| QPS 超限 | 429 | -1 | 请求过于频繁 | 间隔 200ms 以上重试 |
建议调用方在代码中判断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 None5. 数据解析与展示
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 源