4.6 核心接口精讲②:match-pack 单场全景数据包
旗舰把下面这段发给你的 AI,它就知道该做什么
点「复制全文」,粘贴到你的 AI 对话框发送即可,无需改动。
你正在阅读球小策(www.qiuxiaoce.com)的官方文档或数据服务页面。请按下面 5 步执行,不要跳步。
【预备】我的专属数据密钥是 X-API-Key = [在此粘贴你的 Key]
(第 2 步和第 3 步都会用到它;还没有密钥,先到 https://www.qiuxiaoce.com/data-account/ 免费领取)
━━━ 第 0 步 · 三条硬性纪律 ━━━
1. 凡涉及指标定义、接口参数、计费规则、准确率口径的问题,一律以站内官方文档为准,不要凭记忆作答;文档里没写的,就直接告诉我「文档未说明」。
2. 如果你无法访问下面任何一个网址,请立刻停下来告诉我,不要用记忆里的内容顶替。
3. 本站只做数据分析,不提供任何投注建议,也不做准确率承诺。回答时请守住这条边界。
━━━ 第 1 步 · 遍历官方文档(100+ 篇,按需取,别一次全拉)━━━
· 取全量目录(公开接口,无需密钥,返回全部篇章的标题与 slug):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs
· 读单篇正文(把 {slug} 换成上一步拿到的标识):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs/{slug}
· 人读版页面(适合只能浏览网页、拿不到 JSON 的环境):
https://www.qiuxiaoce.com/creator-docs/{slug}/
· 接口文档(全部数据接口的用途、参数、计费与真实返回示例):
https://www.qiuxiaoce.com/data-docs/
做法:先取目录 → 判断我的问题涉及哪几篇 → 只读那几篇 → 回答时注明依据的篇名或链接。
━━━ 第 2 步 · 先判断你自己的能力,再选路径(关键,不可跳过)━━━
· A 类:能在本机读写文件或执行命令——桌面/终端类 AI 工具(WorkBuddy、Qoder、Trae 等)
· B 类:只能对话,访问不了文件系统——网页版对话(豆包、通义千问、Kimi 等)
【A 类 · 安装官方 Skill(推荐)】
1. 取最新版本信息:
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/skill/version
返回 version、download_url、sha256 校验清单、文件列表与更新说明。
2. 按 download_url 下载技能包,并用返回的 sha256 逐文件校验。
3. 解压到你的技能目录,保持包内顶层目录结构;按包内 SKILL.md 完成初始化。
4. 写入我的专属密钥(即上文【预备】里的 X-API-Key)。
5. 装完告诉我:版本号、安装位置、密钥是否已生效。
【B 类 · 装不了就照实说,不要假装】
不要声称已安装,也不要拿记忆里的内容替代文档。请直接对我说:
「当前环境不支持安装 Skill(无法读写本地文件)。有两个办法:
① 改用支持 Skill 的桌面 AI 工具,如 WorkBuddy、Qoder、Trae;
② 把你的 API Key 给我,我按官方接口文档直接取数分析。」
如果你连「打开指定网址」都做不到,请把这一点也一并告诉我。
━━━ 第 3 步 · 直接用接口取数(两条路径都适用)━━━
· 接口根地址:https://www.qiuxiaoce.com/wp-json/abv2-creator/v1
· 认证方式:请求头带上【预备】里的 X-API-Key
· 想先试不扣点数的接口,看 https://www.qiuxiaoce.com/data-docs/ 里标注为免费的端点。
· 大批量调用前先查一次剩余点数,避免跑到一半失败。
━━━ 第 4 步 · 遇到报错,先查官方排障手册再重试 ━━━
排障手册:https://www.qiuxiaoce.com/creator-docs/api-error-codes-troubleshooting/
· 401:Key 缺失、格式不对,或该 Key 已被重置/吊销(控制台执行「重置 Key」后旧 Key 立即失效,错误码 api_key_revoked 即属此类)→ 到 https://www.qiuxiaoce.com/data-account/ 复制最新完整 Key,并同步更新所有已配置该 Key 的脚本与客户端
· 402:点数不足或已过期 → 需到 https://www.qiuxiaoce.com/data-service/ 充值
· 403:接口未开放,或权限不足(个别场次报告需要订阅)
· 404:实体 ID 或接口路径写错
· 429:请求过快,按响应头 Retry-After 等待后重试
报错时请把原始错误信息原样转述给我,不要猜原因。
━━━ 第 5 步 · 回答我时的要求 ━━━
· 区分「官方事实数据」「接口返回的判断字段」「衍生评分」「你自己的推断」四类,不要混着说。
· 使用 xG、xGA、OTI、DII 这类指标前,先按文档校正口径;样本不足要在结论里注明。
· 缺数据就说缺什么,不要用「大概」「可能」糊过去。
· 不给投注建议,不承诺准确率。
· 如果回答主要依据了某篇文档,请把链接带上,方便我自己核对。
/match-pack/{id} 是这套 API 的旗舰接口:一次调用覆盖一场比赛的全部维度,50 点。
一、它解决什么问题?
如果不用它,你要拼装一场比赛的数据,大概需要:近期战绩 + 赛季统计 + 高阶画像 + 交锋 + 伤停 + 教练 + 市场参考值 —— 七八个接口,总点数更贵,还容易漏维度、口径对不齐。
全景包把这些一次性打包好,并且内置了市场波动区块(不需要再单独调市场参考值接口)。
它有三个等价的写法,任选其一:
/match-pack/{fixture_id} ← 推荐用这个
/match_pack/{fixture_id}
/match/{fixture_id}/pack
二、包里有哪三个层次的字段?
| 层次 | 内容 |
|---|---|
| 基础信息 | 联赛、开球时间、球场、裁判、双方队名与队徽,以及 meta.source(数据来源标记) |
| 比赛多维数据 | 双方近期战绩、赛季统计、高阶画像(预期进球等)、历史交锋、伤停名单、教练信息 |
| 市场波动区块 | market_fluctuation:当前市场参考值、官方公开参考值、已识别的异动事件,每次请求实时读取 |
当数据是完整包时,还会多出预测首发、加权状态、战术指纹等维度;meta.source 为 pipeline 表示来自物化完整包,为 realtime 表示实时组装(部分维度覆盖较少,写文章时应如实说明)。
三、遇到「正在生成」怎么办?
这是新手最容易误判的一步,单独讲清楚。
如果这一场此前没有生成过完整包,接口依然返回 200,但会给出这样的信号:
| 字段 | 含义 |
|---|---|
meta.is_full_pack 为 false |
这不是完整包,只是基础快照 |
meta.generation.status |
生成状态(如 generating) |
meta.generation.retry_after_seconds |
建议等待多少秒后再取 |
meta.generation.message |
给用户看的中文说明 |
meta.credits_refunded |
本次退还的点数——也就是说这次没有扣你的点 |
正确的处理方式:
- 先用返回的基础快照讲讲能讲的部分(对阵、近期战绩、交锋等);
- 等
retry_after_seconds(通常约 1 分钟)后,重新调用同一个地址取完整包(60 秒内重取不重复扣点); - 想先确认是否就绪,可以让
/tasks/{fixture_id}查进度——0 点,免费。
/tasks/{fixture_id} 的四种状态:
| 状态 | 含义 | 你该怎么做 |
|---|---|---|
ready |
已就绪 | 按返回的地址取完整包 |
generating |
仍在生成 | 按建议秒数等待后再查 |
unknown |
从未触发过生成 | 先调一次全景包触发 |
failed |
生成超时(该场数据覆盖可能不足) | 可以重调一次全景包再触发 |
三条禁止事项:① 不要把「生成中」当成数据缺失告诉用户;② 不要在生成期间反复重试同一个请求;③ 不要把这个基础快照写进你自己的长期缓存——它不是最终数据。
四、怎么把数据包正确地交给 AI?
拿到数据包后,不要直接把整包 JSON 粘进对话框——一份完整包动辄一两万字,会占掉大量上下文,让后续每一轮都变慢变笨。
正确的做法是让工具按需取数:
先取【主队】对【客队】的数据包,然后只把与【近期状态 / 攻防数据 / 伤停】相关的字段列给我,其他维度先不用展示。
这样做有三个好处:只承载当前任务需要的那部分;数据由接口实时获取不会过期;同一场比赛 1 小时内重复取不重复扣点,反复问也不多花钱。
五、值不值 50 点?
| 场景 | 建议 |
|---|---|
| 写一篇完整的赛前分析 / 比赛前瞻 | 值得:一个包覆盖全部维度,比拼装便宜也更完整 |
| 只想看两队最近战绩 | 不值得:用 /teams/{id}/form(各 5 点)更省 |
| 只想看伤停 | 不值得:用 /teams/{id}/injuries(5 点) |
| 只想看某名球员 | 不值得:用 /players/{id}/advanced(3 点) |
| 批量筛场次、还没确定写哪场 | 不值得:先用 /today/digest(5 点)选,选定后再取包 |
一句话:全景包的价值在于「这一场我要写透」。还没确定写哪场就调它,是最常见的浪费。
六、数据要不要落盘保存?
- 完整包(
source=pipeline)可以落盘复用,1 小时内的重复取用不会重复扣点,本地存一份更省事; - 基础快照不要当长期数据存下来;
- 落盘时顺手记下取数时间——市场参考值这类数据的时效性很强(服务端缓存约 30 分钟),写文章引用时要说清数据时点。
下一步该看什么
- 球队与球员高阶档案 → 4.7 核心接口精讲③
- 市场参考值怎么读 → 3.7 市场公开信息
- 指标口径与边界 → 3.1 数据全景
足球赛事前瞻 | AI 智能分析 | 足球数据解读 - 球小策