4.3 跑通第一个请求:curl / Python / JS 三语言示例
实操
内容太多,看不完或者看不太懂?
复制一段话发给你的 AI,它会自己读完官方文档、装好技能包,再来回答你的问题。
点这里复制给 AI →
想知道每项数据覆盖了哪些赛事?
88 项赛事的数据项覆盖情况一览:赛程比分、首发阵容、球员与球队统计、进阶指标、伤停、天气等,每日自动统计并如实公开。
查看数据覆盖说明 →
把下面这段发给你的 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 这类指标前,先按文档校正口径;样本不足要在结论里注明。
· 缺数据就说缺什么,不要用「大概」「可能」糊过去。
· 不给投注建议,不承诺准确率。
· 如果回答主要依据了某篇文档,请把链接带上,方便我自己核对。
复制后直接发给你的 AI(豆包、千问、WorkBuddy、Qoder 等都可以)。
这一篇的目标只有一个:让你亲手跑通第一个请求。从最便宜的余额自查开始,一步步加码到旗舰接口。
完全不会写代码?先看 4.1 的路线 A——装上 Skill,对着 AI 说人话就行,本篇是给要自己动手调接口的读者准备的。
一、怎么先花 0 点验证连通性?
余额自查是免费接口,用它验证「密钥对不对、网络通不通」最合适。下面四种方式选一种,跑通即可。
方式一 · Mac 或 Linux 终端怎么调?
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota'
-H 'X-API-Key: YOUR_API_KEY_HERE'
Windows 用户要注意什么?
Windows 自带的 PowerShell 里,curl 是另一个命令的别名,参数写法完全不同,直接粘贴上面的命令会报错。两个办法:
- 推荐:用
curl.exe代替curl(Windows 10 以上自带),命令其余部分不用改; - 或者用 Git Bash / WSL 的终端,原样粘贴即可。
# Windows PowerShell:注意是 curl.exe
curl.exe -s "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota" -H "X-API-Key: 你的密钥"
方式三 · Python 怎么调?
import os, requests
BASE = "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1"
KEY = os.environ["QIUXIAOCE_API_KEY"] # 建议用环境变量,不要写死在代码里
def get(path, **params):
r = requests.get(f"{BASE}{path}", params=params,
headers={"X-API-Key": KEY}, timeout=30)
r.raise_for_status()
return r.json()
print(get("/quota"))
方式四 · JavaScript 怎么调?
const BASE = 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1';
const KEY = process.env.QIUXIAOCE_API_KEY;
async function get(path, params = {}) {
const url = new URL(BASE + path);
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
const res = await fetch(url, { headers: { 'X-API-Key': KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
return res.json();
}
get('/quota').then(console.log);
返回里能看到剩余点数、有效期和限流配置,就说明密钥、网络、认证三件事全部打通了。
二、怎么花 2 点拿到一场比赛?
先用最便宜的赛程接口,把「日期 → 比赛」这条链路跑一遍:
# 查某一天的赛程(2 点)
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/fixtures?date=2026-09-16&limit=10'
-H 'X-API-Key: YOUR_API_KEY_HERE'
返回的每一场里都有一个 fixture_id——这个数字是后面所有数据接口的钥匙,先把它记下来。
三、第三步:花 50 点,跑通旗舰接口
# 单场全景数据包(50 点)—— 把 {id} 换成上一步拿到的 fixture_id
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/match-pack/1557403'
-H 'X-API-Key: YOUR_API_KEY_HERE' -o pack.json
import json
pack = get("/match-pack/1557403")
print(pack["meta"]["source"]) # pipeline = 完整包;realtime = 实时组装(部分维度较少)
print(json.dumps(pack["pack"], ensure_ascii=False)[:500])
遇到「正在生成」是正常的,不是报错。如果这场比赛此前没有生成完整包,接口会返回一个基础快照,并告诉你大约 1 分钟后可以重取,而且这次没有扣你的点数。正确处理方式:等它就绪后重新调用同一个地址(60 秒内重取不重复扣点)。详细说明见 4.6 单场全景数据包。
四、把结果存下来,别只打印
数据拿到手就落盘,是省点数最直接的习惯。同一个文件读一百次不要钱,重新调一次接口要钱:
import json, pathlib
def save(name, data):
p = pathlib.Path("data") / f"{name}.json"
p.parent.mkdir(exist_ok=True)
p.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
print("saved →", p)
save("pack_1557403", get("/match-pack/1557403"))
如果你用的是官方 Skill,这一步已经内置了:它带本地数据层,会自动把赛果和研报永久落库、其余数据按 TTL 缓存,命中就不扣点。
五、三个新手最容易卡住的地方
| 现象 | 原因与解法 |
|---|---|
| 返回 402 | 点数不足或已过期。先调 /quota(0 点)看余额与有效期 |
| 返回 404 | 几乎都是 ID 错了。先用搜索接口确认正确 ID,不要猜 |
| 返回 429 | 触发了每分钟 30 次的限流。等一分钟,或在循环里加间隔 |
完整的排查手册见 4.8 错误码与排障。
💬 让 AI 帮你把这个脚本写对(复制发送) 实战
我在调用球小策创作者 API,基础信息如下:
- Base URL:https://www.qiuxiaoce.com/wp-json/abv2-creator/v1
- 认证:请求头 X-API-Key
- 限流:每分钟 30 次;同一个请求 60 秒内重复调用不重复扣点
请帮我写一个【Python / JavaScript】脚本,完成:【用一句话描述任务,例如「取某个日期全部比赛,并逐场拉单场数据包」】。
要求:
1. 密钥从环境变量读取,不要写死在代码里;
2. 请求之间要有节流(避免触发限流),并且对 429 做重试;
3. 对 402 / 403 / 404 分别给出明确的错误提示(不要只抛一个通用异常);
4. 结果落盘成文件,重复运行时可选择跳过已存在的文件;
5. 在代码注释里写清每一处对应的接口点数。
先给我完整的代码,不要先解释一大段。写完后单独列一份「这段代码一共会花多少点」的说明。
下一步该看什么
- 46 个接口怎么选 → 4.4 接口地图
- 赛程域接口怎么用 → 4.5 核心接口精讲①
- 报错与限流处理 → 4.8 错误码与排障
足球赛事前瞻 | AI 智能分析 | 足球数据解读 - 球小策