适用场景当你在搭建王者荣耀相关的数据站、战队管理工具、直播弹幕互动或战绩分享机器人时需要获取玩家的对局信息。本API通过王者营地小程序接口提供搜索玩家、查询角色列表、获取历史战绩及KDA统计三个能力。本文的目标是给出一个从零开始、可复制执行的curl示例让开发者在拿到API Key后五分钟内跑通第一个请求。接口能力与限制接口地址POST https://v1.apizero.cn/api/wzry-battle请求方法POSTContent-Type 为application/json。QPS 限制2次/秒超出后可能返回限流错误。能力说明actionsearch根据昵称关键词搜索玩家返回符合条件的玩家列表及基础信息。actionroles根据玩家user_id查询其拥有的游戏角色不同区服。actionbattles根据玩家user_id和角色role_id拉取历史战绩支持翻页与模式筛选。注意该接口依赖王者营地小程序数据数据更新频率以官方营地为准无法保证实时性。鉴权方式请求头必须携带X-API-Key值为你在API平台申请到的私有密钥。示例中的$APIZERO_API_KEY需要替换为实际密钥。最小可运行示例三步搭建以下三个步骤分别对应三个action每个步骤都提供可直接运行的curl命令。请先将环境变量APIZERO_API_KEY设置好或直接替换命令中的字符串。第一步搜索玩家actionsearch假设你想搜索ID包含“李白”或“梦泪”等关键词的玩家执行curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:search,keyword:梦泪} \ https://v1.apizero.cn/api/wzry-battle成功响应示例{ code: 200, data: [ { user_id: 123456789, nickname: 梦泪, avatar: https://example.com/avatar.png }, { user_id: 987654321, nickname: 梦泪的粉丝, avatar: https://example.com/avatar2.png } ], message: success }第二步查询玩家角色actionroles传入上一步获得的user_id获取该玩家所有的游戏角色curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:roles,user_id:123456789} \ https://v1.apizero.cn/api/wzry-battle响应示例示意{ code: 200, data: [ { role_id: role_a1b2c3, role_name: 李白传人, area: 微信1区, level: 50, rank: 最强王者 }, { role_id: role_d4e5f6, role_name: 梦泪本泪, area: QQ1区, level: 45, rank: 星耀 } ], message: success }记录目标角色的role_id。第三步获取历史战绩actionbattles传入user_id、role_id以及可选的翻页参数拉取最近的对局记录curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:battles,user_id:123456789,role_id:role_a1b2c3,option:0,pages:1,last_time:0} \ https://v1.apizero.cn/api/wzry-battle参数说明option: 0表示全部模式1排位2巅峰3娱乐。pages: 1表示拉取最近一页约30条。last_time: 0表示从最新记录开始翻页。响应结构示意关键字段{ code: 200, data: { list: [ { game_id: game_xxx, hero: 李白, result: win, kills: 12, deaths: 3, assists: 8, mode: 排位赛, time: 1720000000, score: 14.5, mvp: true } // ... 更多记录 ], has_more: true, next_last_time: 1719900000 }, message: success }has_more指示是否还有更多数据可以通过将last_time设为next_last_time继续翻页。以上三步构成了一个完整的“战报查询”最小链路。你可以在终端中依次执行这三个curl命令验证API的可用性。请求参数详解下表汇总所有请求体字段数据类型均为string或number由JSON类型决定字段类型必填适用action说明actionstring是全部取值 search / roles / battleskeywordstring否search玩家昵称关键词模糊匹配user_idstring否roles, battles玩家唯一标识由search获得role_idstring否battles角色标识由roles获得last_timenumber否battles翻页游标Unix时间戳秒级0表示最新optionnumber否battles模式筛选0全部 1排位 2巅峰 3娱乐pagesnumber否battles拉取页数取值范围1~3每页约30条注意last_time的值通常从上一轮响应的next_last_time中获取。若只拉取latest设为0即可。响应字段解读所有请求的响应结构统一为{ code: 200, data: 对象或数组, message: success }code整型状态码200表示成功其他为错误。data具体业务数据格式因action而异search玩家列表[ {user_id, nickname, avatar}, ... ]roles角色列表[ {role_id, role_name, area, level, rank}, ... ]battles历史战绩对象{ list: [ {game_id, hero, result, kills, deaths, assists, mode, time, score, mvp}, ... ], has_more, next_last_time }message状态描述。KDA可在battles的列表中直接获得kills / deaths / assistsscore为综合评分。错误处理常见错误码及原因code含义处理建议400请求参数缺失或格式错误检查action是否拼写正确必填字段是否提供JSON是否合法401API Key 无效或缺失确认请求头携带了正确的X-API-Key403权限不足或IP被限制检查API配额说明是否允许该接口调用或联系平台429请求频率超限QPS 2/s增加请求间隔或使用队列控制并发500服务端内部错误重试若持续则联系技术支持1001未搜索到匹配玩家search更换keyword或确认玩家昵称正确1002玩家不存在或role_id错误battles重新运行roles获取正确的role_id所有错误响应仍为JSON格式message字段会给出具体描述。工程化注意事项API Key 安全禁止将密钥硬编码在客户端代码或公开仓库中使用环境变量或服务端配置管理。频率控制QPS上限2次/秒建议在调用侧实现节流如令牌桶避免触发429。分页策略battles接口支持last_time游标分页注意pages最大为3若需更多数据需多次请求并拼接。数据缓存对历史战绩等不频繁变化的数据设置合理的缓存如30秒减少重复请求。错误重试对于5xx错误采用指数退避重试如1s、2s、4s最多3次。4xx错误无需重试。参数校验前端传入role_id等字段前应做非空校验避免发送无效请求。时区处理响应中的时间戳为Unix秒级展示时转换为本地时间。参考文档接口原始文档接口概述页注意文档中的curl模板使用了环境变量$APIZERO_API_KEY请根据实际环境替换。更多字段定义以官方文档为准。