4.3 跑通第一个请求：curl / Python / JS 三语言示例

这一篇给你三种语言的最小可运行示例。提示：如果你已登录，下面的代码会把你真实的密钥自动填进去，复制即可运行。

一、先验证连通性：余额自查（0 点）#

curl#

curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Python#

import requests

API_KEY = 'YOUR_API_KEY_HERE'
BASE = 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1'

r = requests.get(f'{BASE}/quota', headers={'X-API-Key': API_KEY}, timeout=10)
print(r.status_code, r.json())

JavaScript（Node 18+）#

const API_KEY = 'YOUR_API_KEY_HERE';
const BASE = 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1';

const res = await fetch(`${BASE}/quota`, { headers: { 'X-API-Key': API_KEY } });
console.log(res.status, await res.json());

如果返回 200 且包含余额信息，说明认证链路已经打通。

二、拿一场比赛的调度顺序#

调用任何详情接口前，你都需要先拿到 ID。标准顺序是：

1. 查今日赛事总览或比赛日程 → 拿到 fixture_id 与球队 id；
2. 用 ID 去调详情类接口。

第一步：查看今日赛事总览#

curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/today/digest' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

第二步：查询比赛日程（可按日期/联赛筛选）#

curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/fixtures?date=2026-09-13' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

返回的 JSON 中会包含每场比赛的 fixture_id。

三、调用旗舰接口：单场全景数据包#

这是最常用的接口，一次返回单场比赛的完整数据。

curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/match-pack/1557403' 
  -H 'X-API-Key: YOUR_API_KEY_HERE' 
  -H 'Accept: application/json'

Python 版本：

import requests, json

API_KEY = 'YOUR_API_KEY_HERE'
BASE = 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1'

def get_match_pack(fixture_id):
    url = f'{BASE}/match-pack/{fixture_id}'
    headers = {'X-API-Key': API_KEY, 'Accept': 'application/json'}
    r = requests.get(url, headers=headers, timeout=20)

    # 观察去重状态：命中缓存不扣点
    dedup = r.headers.get('X-Dedup-Hit', '0')
    print(f'status={r.status_code} dedup={dedup}')

    if r.status_code != 200:
        print('错误:', r.text)
        return None

    data = r.json()
    # 建议：把结果落盘缓存，避免重复扣点
    with open(f'/tmp/match_{fixture_id}.json', 'w', encoding='utf-8') as f:
        json.dump(data, f, ensure_ascii=False, indent=2)
    return data

if __name__ == '__main__':
    get_match_pack(1557403)

四、推荐的工程封装#

import os, json, time, requests
from pathlib import Path

API_KEY = os.environ.get('QIUXIAOCE_API_KEY', 'YOUR_API_KEY_HERE')
BASE = 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1'
CACHE_DIR = Path('./cache')
CACHE_DIR.mkdir(exist_ok=True)

class QiuXiaoCeClient:
    '''球小策 API 极简客户端（含本地缓存，规避重复扣点）'''

    def __init__(self, key=API_KEY):
        self.headers = {'X-API-Key': key, 'Accept': 'application/json'}

    def get(self, path, params=None, cache_key=None, ttl=86400):
        # 本地缓存：历史数据不会变化，命中直接返回
        if cache_key:
            f = CACHE_DIR / f'{cache_key}.json'
            if f.exists() and time.time() - f.stat().st_mtime < ttl:
                return json.loads(f.read_text(encoding='utf-8'))

        r = requests.get(f'{BASE}{path}', headers=self.headers, params=params, timeout=20)
        r.raise_for_status()
        data = r.json()

        if cache_key:
            (CACHE_DIR / f'{cache_key}.json').write_text(
                json.dumps(data, ensure_ascii=False), encoding='utf-8')
        return data

client = QiuXiaoCeClient()
print(client.get('/quota', cache_key=None))
print(client.get('/today/digest', cache_key='digest_20260913', ttl=1800))

五、三个注意事项#

• 超时设置不要低于 15 秒：部分数据包较大，超时过短会误判失败；
• 观察 X-Dedup-Hit 头：调试时确认是否命中免扣；
• 不要在前端直接调用：密钥会暴露在浏览器中，务必通过你自己的后端转发。

下一步该看什么#

• 全部 46 个接口的选型指南 → 4.4 接口地图
• 遇到报错怎么办 → 4.8 错误码排障手册