适用场景
王者荣耀全国战力查询 API 为开发者提供了一套标准化的接口，可以获取以下两类核心数据：
- 英雄列表：返回 130+ 个英雄的中文名、ename（数字 ID）、称号、头像 URL 等元信息，可用于构建英雄选择器或数据展示 UI。
- 战力分布数据：针对指定英雄和区服（Android QQ / Android 微信 / iOS QQ / iOS 微信），查询其在全国各省、市、区的战力排名分布（约 90 条记录），支持返回完整列表、仅最低战力相近排名或仅最高战力相近排名。
典型应用包括：
- 开发“国服战力查询”小程序或公众号，用户输入英雄和区服即可查看所在省份的门槛战力。
- 爬取多个英雄的历史战力数据，用于分析版本强度变化或制作数据报告。
- 在游戏社群工具中集成战力对比功能，辅助玩家决策。
接口能力边界
- 请求方式：GET
- 基准地址：
https://v1.apizero.cn/api/wzry - 速率限制：5 QPS（每秒请求数），超出后可能返回 429 状态码或限流提示，具体以服务端实际行为为准。
- 数据新鲜度：响应中包含
syn_date字段（如"2026-05-06"），表示该数据的同步日期，并非实时数据，通常为每日或每周更新，请勿期望秒级实时。 - 查询范围：
action=query时返回约 90 条省/市/区级记录，覆盖主要地区和部分相近排名；完整榜单可能受限于官方数据源。
请求参数详解
Query 参数
| 参数名 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
action | 是 | string | 操作类型：heroes获取英雄列表，query获取战力查询 | query |
hero | 否 | string | 英雄中文名（如赵云）；与hero_id二选一，action=query时必传其一 | 赵云 |
hero_id | 否 | number | 英雄 ename（如赵云为107）；与hero二选一，若同时提供则hero_id优先级更高 | 107 |
zone | 否 | string | 区服代码：aqq= Android QQ,awx= Android 微信,iqq= iOS QQ,iwx= iOS 微信；action=query时必填 | aqq |
type | 否 | string | 返回类型：all完整列表（默认），min仅最低战力及相近排名，max仅最高战力及相近排名 | min |
注意：当
action=heroes时，只需传入action参数，其余参数会被忽略。
Header 参数
| 参数名 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
Authorization | 否 | string | API Key 鉴权头，格式Bearer sk_live_xxx；匿名调用时每日有调用次数限制（具体以文档为准） | Bearer sk_live_xxxxxxxxxxxxxx |
鉴权方式也支持通过X-API-Key头传递，两种方式二选一。匿名调用可省略鉴权头，但每日配额有限，超出后可能返回 403 或 429。建议在生产环境使用 API Key 以避免中断。
curl 请求示例
获取英雄列表
curl -sS -X GET \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://v1.apizero.cn/api/wzry?action=heroes"查询战力（匿名调用）
curl -sS -X GET \ "https://v1.apizero.cn/api/wzry?action=query&hero=赵云&zone=aqq&type=min"查询战力（带鉴权）
curl -sS -X GET \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://v1.apizero.cn/api/wzry?action=query&hero_id=107&zone=iwx&type=max"Python 代码接入示例
以下 Python 脚本演示如何先获取英雄列表，再查询某个英雄的最低战力分布。
import requests BASE_URL = "https://v1.apizero.cn/api/wzry" API_KEY = "sk_live_xxxxxxxxxxxxxx" # 可选 HEADERS = {} if API_KEY: HEADERS["Authorization"] = f"Bearer {API_KEY}" # 1. 获取英雄列表 params = {"action": "heroes"} resp = requests.get(BASE_URL, params=params, headers=HEADERS) heroes_data = resp.json() if heroes_data.get("code") == 0: hero_list = heroes_data["data"] # 打印前5个英雄 for hero in hero_list[:5]: print(f"{hero['ename']} - {hero['cname']}（{hero['title']}）") else: print("获取英雄列表失败:", heroes_data.get("msg")) exit(1) # 2. 查询赵云（ename=107）在 Android QQ 区的最低战力 params = { "action": "query", "hero_id": 107, "zone": "aqq", "type": "min" } resp = requests.get(BASE_URL, params=params, headers=HEADERS) query_result = resp.json() if query_result.get("code") == 0: data = query_result["data"] print(f"英雄：{data['hero']['name']}") print(f"区服：{data['zone']['system']} {data['zone']['platform']}") print(f"数据类型：{data['type']}") print(f"数据日期：{data['syn_date']}") rank_data = data["rank_data"] extreme = rank_data.get("extreme", {}) for level in ["province", "city", "district"]: if level in extreme: info = extreme[level] print(f"{level}: {info['address']}，战力 {info['rank']}") similar = rank_data.get("similar", {}) for level in ["province", "city", "district"]: items = similar.get(level, []) for item in items: print(f"相近 {level}: {item['address']}，战力 {item['rank']}") else: print("查询失败:", query_result.get("msg"))注意：实际返回的数据结构可能因type参数而异，务必根据响应中的type_code进行解析。
返回字段解读
以下是action=query且type=min时的 JSON 结构示例（已脱敏）：
{ "code": 0, "msg": "成功", "request_id": "abc123def456", "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": "530000", "address": "云南", "level": "province", "rank": 4500 }, "city": { "adcode": "460200", "address": "海南/三亚市", "level": "city", "rank": 1800 }, "district": { "adcode": "110105", "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" } } }关键字段说明
| 路径 | 类型 | 含义 |
|---|---|---|
code | int | 业务状态码，0 表示成功，非 0 表示异常 |
msg | string | 状态描述 |
request_id | string | 本次请求的唯一标识，可用来排查问题 |
data.hero | object | 英雄基本信息（name、ename、title、avatar） |
data.rank_data.extreme | object | 各级（province/city/district）的战力极值（当 type=min 时为最低战力，type=max 时为最高战力） |
data.rank_data.extreme.province.rank | number | 省级战力数值（国服最低/最高） |
data.rank_data.similar | object | 与极值战力相近的排名列表，keys 为province/city/district，值为数组（可能为空） |
data.syn_date | string | 数据同步日期，格式YYYY-MM-DD |
data.type_code | string | 返回类型：all、min、max，与请求参数一致 |
data.zone | object | 区服信息，包含 code、platform、system |
当type=all时，rank_data的结构会不同，不再有extreme和similar，而是直接返回一个约 90 项的数组（按 level 混合排列）。建议根据type_code动态解析。
常见错误处理
| HTTP 状态码 | 可能原因 | 处理建议 |
|---|---|---|
| 200（code≠0） | 参数错误、鉴权失败、限流 | 查看msg字段确定具体错误，如"缺少必要参数"、"无权限访问"、"请求过于频繁" |
| 400 | 请求格式错误（如无效参数值） | 检查是否传入了非法字符或类型不匹配 |
| 403 | 鉴权失败或匿名用户超出每日限额 | 检查 API Key 是否正确，或等待配额重置 |
| 429 | 请求频率超限（QPS > 5） | 实现指数退避重试，或将请求分散到不同时间片 |
| 5xx | 服务端内部错误 | 可重试，若持续失败需联系 API 提供方 |
参数校验注意事项
hero和hero_id只能二选一，同时传时以hero_id为准。zone必须为aqq/awx/iqq/iwx之一，否则返回错误。- 英雄名称必须与官方完全一致（如“赵云”不能写作“赵子龙”），建议先调用
action=heroes获取合法名称列表。
工程化注意事项
- 缓存策略：英雄列表变化频率极低（基本只在版本更新时增加新英雄），建议本地缓存至少 24 小时。战力数据建议缓存 1 小时以上，避免频繁请求被限流。
- 限速与重试：QPS 限制为 5，并发请求时需加锁或使用令牌桶控制。推荐使用
retry库在遇到 429 或 5xx 时自动重试（最多 3 次，间隔 1s、2s、4s）。 - 请求 ID 记录：每次请求的
request_id应记录到日志，方便排查问题。 - 参数安全：避免直接将用户输入拼接到 URL 中，应先进行校验或使用 URL 编码。
- 数据分页：
action=query目前不提供分页参数，若需获取全部记录（如type=all时返回约 90 条），直接使用即可。 - 跨平台兼容：不同区服的战力数据独立，查询时需明确用户选择的区服。
实战示例：构建一个简易战力查询 CLI
以下是一个使用 Python 和 argparse 的命令行工具，接受英雄名称、区服、类型参数，输出简要结果：
import argparse import requests import json API_URL = "https://v1.apizero.cn/api/wzry" def main(): parser = argparse.ArgumentParser(description="王者荣耀战力查询 CLI") parser.add_argument("--hero", required=True, help="英雄中文名") parser.add_argument("--zone", required=True, choices=["aqq","awx","iqq","iwx"], help="区服代码") parser.add_argument("--type", default="min", choices=["all","min","max"], help="返回类型") parser.add_argument("--key", default="", help="API Key (可选)") args = parser.parse_args() headers = {} if args.key: headers["Authorization"] = f"Bearer {args.key}" params = { "action": "query", "hero": args.hero, "zone": args.zone, "type": args.type } resp = requests.get(API_URL, params=params, headers=headers) if resp.status_code != 200: print(f"HTTP {resp.status_code}: {resp.text}") return data = resp.json() if data.get("code") != 0: print(f"业务错误: {data.get('msg')}") return info = data["data"] print(f"\n{info['hero']['name']} - {info['zone']['system']} {info['zone']['platform']}") print(f"数据日期: {info['syn_date']}") rank_data = info["rank_data"] if args.type != "all": extreme = rank_data.get("extreme", {}) for level in ["province","city","district"]: if level in extreme: item = extreme[level] print(f"{level}: {item['address']} -> 战力 {item['rank']}") similar = rank_data.get("similar", {}) for level in ["province","city","district"]: items = similar.get(level, []) if items: print(f"相近 {level}: {', '.join([f'{i["address"]}({i["rank"]})' for i in items])}") else: # all 类型直接输出列表数量 items = rank_data.get("list", []) print(f"共 {len(items)} 条记录") for item in items[:5]: # 显示前5条 print(f" {item['address']} - {item['rank']}") if __name__ == "__main__": main()使用方法：
python wzry_cli.py --hero 赵云 --zone aqq --type min参考文档
- 接口文档页
- 原始 Markdown 文档
- 官方英雄列表源：https://pvp.qq.com/web201605/js/herolist.json（仅做参考，本接口已聚合）
