前言在开发棋牌游戏助手、英雄战力监控或社交平台播报机器人时获取王者荣耀英雄在全国各区服的战力分布是一项常见需求。本文围绕王者荣耀全国战力查询 API详细拆解其请求参数、鉴权方式、响应字段并结合工程化场景给出接入建议。接口能力与适用场景该接口使用 GET 方式调用基础地址为https://v1.apizero.cn/api/wzry单接口整合两大功能英雄列表查询获取全部 130 英雄的ename数字标识、name中文名、title称号以及头像 URL。战力分布查询针对指定英雄在指定区服Android QQ、Android 微信、iOS QQ、iOS 微信返回省级、市级、区级三个层级的战力排名数据并附带近似的全国排名。典型使用场景工具类应用展示某英雄当前省级最低上榜战力。数据看板按区服统计热门英雄的准入分数线。Bot 消息用户输入“赵云 安卓QQ 最低战力”后自动查询并回复。请求方式与鉴权请求方法GETHTTP Header参数名必填说明Authorization否API Key 鉴权格式Bearer sk_live_xxx。匿名调用时可省略但有每日 50 次限制。若需要更高调用频率请将 API Key 附在请求头中-H Authorization: Bearer sk_live_your_key请求参数详解Query 参数总表参数类型必填说明示例值actionstring是操作类型heroes获取英雄列表query查询战力分布queryherostring条件必填英雄中文名与hero_id二选一。当actionquery时必选其一。赵云hero_idnumber条件必填英雄ename数字编号。与hero二选一且优先级高于hero。107zonestring条件必填区服代码aqqAndroid QQ、awxAndroid 微信、iqqiOS QQ、iwxiOS 微信。actionquery时必填。aqqtypestring否返回类型all完整列表默认、min各级最低战力相近排名、max各级最高战力相近排名min参数组合逻辑英雄列表模式只需actionheroes无需传递 hero/zone/type。战力查询模式actionquery必须同时提供英雄标识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?actionheroes | jq .无鉴权时直接调用即可每日有限额返回一个包含code: 0的 JSON 数组其中data字段为英雄对象列表。查询赵云在 Android QQ 区的最低战力curl -sS -X GET \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ https://v1.apizero.cn/api/wzry?actionqueryhero%E8%B5%B5%E4%BA%91zoneaqqtypemin注意hero参数需进行 URL 编码中文→%E8%B5%B5%E4%BA%91。若使用hero_id可直接传数字无需编码hero_id107。查询指定英雄的完整战力分布all 类型curl -sS -X GET \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ https://v1.apizero.cn/api/wzry?actionqueryhero_id107zoneiwxtypeall响应结构解读成功时返回格式如下以typemin为例{ 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 中同级的相近排名列表typemin时表示低于当前值的其他省份/城市/区。typemax时则为高于当前值的其他区域。data.syn_date数据同步时间格式YYYY-MM-DD。data.type与data.type_code对应请求的type参数。data.zone区服信息。当typeall时extreme字段不再体现而是直接返回一个完整的list数组包含省市区混合排序的约 90 条记录。错误处理与常见问题错误场景HTTP Statuscodemsg 示例处理方法缺少必填参数400-1参数错误缺少action按文档补全参数英雄名不存在2001001英雄“李四”不存在使用英雄列表接口校验名称区服代码非法400-1zone 参数值非法仅允许 aqq/awx/iqq/iwxAPI Key 无效/额度不足401-1认证失败检查 Key 或更换匿名调用QPS 超限429-1请求过于频繁间隔 200ms 以上重试建议调用方在代码中判断code是否为 0非零时读取msg进行展示或记录request_id用于排查。最佳实践与工程化注意事项1. 缓存英雄列表英雄列表数据相对固定仅在游戏版本更新时变动建议首次启动时调用actionheroes获取并本地缓存如 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, retries3): for i in range(retries): resp requests.get(API_URL, paramsparams, ...) 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 源
前言在开发棋牌游戏助手、英雄战力监控或社交平台播报机器人时获取王者荣耀英雄在全国各区服的战力分布是一项常见需求。本文围绕王者荣耀全国战力查询 API详细拆解其请求参数、鉴权方式、响应字段并结合工程化场景给出接入建议。接口能力与适用场景该接口使用 GET 方式调用基础地址为https://v1.apizero.cn/api/wzry单接口整合两大功能英雄列表查询获取全部 130 英雄的ename数字标识、name中文名、title称号以及头像 URL。战力分布查询针对指定英雄在指定区服Android QQ、Android 微信、iOS QQ、iOS 微信返回省级、市级、区级三个层级的战力排名数据并附带近似的全国排名。典型使用场景工具类应用展示某英雄当前省级最低上榜战力。数据看板按区服统计热门英雄的准入分数线。Bot 消息用户输入“赵云 安卓QQ 最低战力”后自动查询并回复。请求方式与鉴权请求方法GETHTTP Header参数名必填说明Authorization否API Key 鉴权格式Bearer sk_live_xxx。匿名调用时可省略但有每日 50 次限制。若需要更高调用频率请将 API Key 附在请求头中-H Authorization: Bearer sk_live_your_key请求参数详解Query 参数总表参数类型必填说明示例值actionstring是操作类型heroes获取英雄列表query查询战力分布queryherostring条件必填英雄中文名与hero_id二选一。当actionquery时必选其一。赵云hero_idnumber条件必填英雄ename数字编号。与hero二选一且优先级高于hero。107zonestring条件必填区服代码aqqAndroid QQ、awxAndroid 微信、iqqiOS QQ、iwxiOS 微信。actionquery时必填。aqqtypestring否返回类型all完整列表默认、min各级最低战力相近排名、max各级最高战力相近排名min参数组合逻辑英雄列表模式只需actionheroes无需传递 hero/zone/type。战力查询模式actionquery必须同时提供英雄标识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?actionheroes | jq .无鉴权时直接调用即可每日有限额返回一个包含code: 0的 JSON 数组其中data字段为英雄对象列表。查询赵云在 Android QQ 区的最低战力curl -sS -X GET \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ https://v1.apizero.cn/api/wzry?actionqueryhero%E8%B5%B5%E4%BA%91zoneaqqtypemin注意hero参数需进行 URL 编码中文→%E8%B5%B5%E4%BA%91。若使用hero_id可直接传数字无需编码hero_id107。查询指定英雄的完整战力分布all 类型curl -sS -X GET \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ https://v1.apizero.cn/api/wzry?actionqueryhero_id107zoneiwxtypeall响应结构解读成功时返回格式如下以typemin为例{ 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 中同级的相近排名列表typemin时表示低于当前值的其他省份/城市/区。typemax时则为高于当前值的其他区域。data.syn_date数据同步时间格式YYYY-MM-DD。data.type与data.type_code对应请求的type参数。data.zone区服信息。当typeall时extreme字段不再体现而是直接返回一个完整的list数组包含省市区混合排序的约 90 条记录。错误处理与常见问题错误场景HTTP Statuscodemsg 示例处理方法缺少必填参数400-1参数错误缺少action按文档补全参数英雄名不存在2001001英雄“李四”不存在使用英雄列表接口校验名称区服代码非法400-1zone 参数值非法仅允许 aqq/awx/iqq/iwxAPI Key 无效/额度不足401-1认证失败检查 Key 或更换匿名调用QPS 超限429-1请求过于频繁间隔 200ms 以上重试建议调用方在代码中判断code是否为 0非零时读取msg进行展示或记录request_id用于排查。最佳实践与工程化注意事项1. 缓存英雄列表英雄列表数据相对固定仅在游戏版本更新时变动建议首次启动时调用actionheroes获取并本地缓存如 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, retries3): for i in range(retries): resp requests.get(API_URL, paramsparams, ...) 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 源
