API 文档
为个人分析师和 AI 系统提供足球高阶数据。统一通过 API Key 鉴权，返回结构化 JSON。
RESTful API · 可机器自发现 · 统一响应结构
接口检索
按端点路径、中文用途、参数名或响应字段搜索。网页目录与智能体读取的 schema 共用同一份接口契约。
供智能体与聚合平台使用的入口
GET /api/open/schema?view=catalog
GET /api/open/schema?view=catalog&q=伤停
GET /api/open/schema?category=odds&method=GET
目录与字段说明公开可读；业务 API 须携带 X-API-Key，并处于有效试用期内或拥有有效付费会员。到期后 API 额度为 0，开通会员后恢复调用。
1. 获取 API Key
注册账号并登录后，此处将自动显示您的专属 API Key。
2. 鉴权方式
在 HTTP 请求头中携带 X-API-Key 字段：
X-API-Key: vq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3. 基础 URL
https://vfootball.cn/api/open/4. 响应格式
所有接口返回统一 JSON 格式：
{
"success": true,
"data": { ... },
"error": "错误信息（仅失败时）"
}5. 调用额度与突发保护
进阶版 / 每日
10,000 次
突发 200 次/分钟
专业版 / 每日
20,000 次
突发 600 次/分钟
旗舰版 / 每日
100,000 次
突发 2,400 次/分钟
版本决定每日额度、分钟上限与 API 历史查询范围；同版本的月卡、季卡、年卡权益额度一致，周期影响价格和使用时长。季卡另赠2025.01.01—2026.10.06历史数据包；年卡另赠2021 年—2026.10.06的五年历史数据包。赠包范围独立于 API 查询范围。
每日套餐额度及已有每日加量权益优先使用，用完后扣除额外次数包。次数包不按日期清零，会员到期后保留余额，恢复付费会员后可继续使用。
额外次数包对成功的数据请求扣减，合法空结果也计 1 次；正常业务失败不消耗次数包，已预留次数会返还。若返回 error_code=credits_in_doubt，表示结算状态待确认，请稍后查看账户记录。通过 X-API-Credits-Charged 与 X-API-Credits-Remaining 查看已确认的扣次及可用余额。
注册前 3 天可体验旗舰版 API 数据权限（含完整逐事件流），每日 500 次、每分钟 30 次。试用期或付费会员到期后，API 额度为 0，所有业务 API 暂停，含竞彩与竞技场；开通会员后恢复，原 API Key 无需更换。
非旗舰正式会员也可调用逐事件流：每天3场，每场已采集记录的前300条固定样本，已有字段完整保留。北京时间零点重置，同账号所有Key共用；空数据不占场次，请求照常计入API额度。响应中的 preview 表示部分体验数据，不能作整场统计；旗舰版支持完整已采集记录与游标增量。
有效试用期或付费会员的每日额度按北京时间自然日重置，不设周限额或月限额；有效会员加量权益按套餐规则叠加，到期后保留加量权益，恢复会员后继续使用。/api/open/schema 与公开文档可继续读取。竞技场提交、确认、查询不消耗调用额度，仅有效付费正式会员可参赛；其他数据端点进入合法路由后计 1 次（参数错误或上游错误也计入）。到期调用返回 403 membership_required，请开通或续费；有效权益内超出额度返回 429，请按 Retry-After 退避重试，并通过 X-RateLimit-Remaining 与 X-RateLimit-Burst-Remaining 观察剩余额度。
import requests
API_KEY = "你的_API_Key"
BASE_URL = "https://vfootball.cn/api/open"
headers = {
"X-API-Key": API_KEY
}
# 获取今日比赛列表
response = requests.get(
f"{BASE_URL}/matches",
headers=headers,
params={"status": "notstarted", "limit": 10}
)
data = response.json()
print(data)const API_KEY = "你的_API_Key";
const BASE_URL = "https://vfootball.cn/api/open";
// 获取比赛详情（含赔率 + 统计）
async function getMatchAnalysis(matchId) {
const headers = { "X-API-Key": API_KEY };
const [detail, odds, stats] = await Promise.all([
fetch(`${BASE_URL}/matches/detail?match_id=${matchId}`, { headers }),
fetch(`${BASE_URL}/matches/odds?match_id=${matchId}`, { headers }),
fetch(`${BASE_URL}/matches/stats?match_id=${matchId}`, { headers }),
]);
return {
detail: await detail.json(),
odds: await odds.json(),
stats: await stats.json(),
};
}
getMatchAnalysis(12345).then(console.log);# 获取联赛积分榜
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/leagues/standings?league_id=1"
# 获取比赛赔率
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds?match_id=12345"
# 获取比赛必发指数（各市场成交资金分布）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/wom?match_id=12345"
# 获取资金流完整变化点（时间戳 + 新增成交 + 异动标记）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/wom-history?match_id=12345&market=1X2_HOME_FT&limit=500"
# 获取赔率变动序列（初盘 → 每次变动 → 当前，可按 phase 只看滚球盘）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/flow?match_id=12345&phase=live"
# 获取多公司水位面板（轻量，适合 5~15 秒轮询）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/board?match_id=12345"
# 批量获取多场水位面板（最多 20 场）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/board/batch?match_ids=12345,67890"
# 获取竞彩官方在售比赛（聚合）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/jc/matches"
# 获取单场竞彩玩法（平台 match_id 反查）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/jc?match_id=12345"
# 获取滚球实时数据（实时比分/xG/事件流/实时赔率，仅进行中比赛）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/live?match_id=12345"
# 获取滚球关键指标分钟级时序
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/live-series?match_id=12345&minutes=30"每个接口返回的 JSON 字段可通过 /api/open/schema 端点获取字段说明，方便程序化对接。
获取所有端点列表
GET https://vfootball.cn/api/open/schema获取指定端点字段说明
GET https://vfootball.cn/api/open/schema?endpoint=GET%20/matches/detailendpoint 参数值可从端点列表返回的 name 字段获取，需要对空格进行 URL 编码（%20）
📖 字段说明示例
{
"success": true, // 请求是否成功
"data": {
"id": 12345, // 比赛ID
"status": "finished", // 比赛状态
"event_date": "2026-08-15 02:30:00", // 开赛时间
"venue": "...", // 球场
"round": "...", // 轮次
"home_team": { "id": 678, "name": "Bournemouth", "logo": "..." }, // 主队
"away_team": { "id": 679, "name": "Man City", "logo": "..." }, // 客队
"home_score": 2, // 主队 90 分钟常规时间进球
"away_score": 1, // 客队 90 分钟常规时间进球
"final_home_score": 2, // 加时后最终主队进球；无加时等于常规时间
"final_away_score": 1, // 加时后最终客队进球
"extra_time_home_score": null,
"extra_time_away_score": null,
"penalty_shootout_home_score": null,
"penalty_shootout_away_score": null,
"has_extra_time": false,
"has_penalty_shootout": false,
"league_name": "英超", // 联赛名
"league_id": 383 // 联赛ID
}
}赔率接口（变动流） — /api/open/matches/odds
平台赔率数据来自赔率变动流：赛前盘与滚球盘共用同一条序列底座，15 秒级落库，只记录每次变动。本接口按「市场 → 公司」返回当前水位与真初盘，一次调用即可拿到全量公司（上游有多少家就返回多少家）× 5 个市场的全部盘口（含半场亚盘、半场大小球）；纯读库、不消耗上游额度、不限调用频率（受平台通用限流约束）。
公司与市场：
- 公司（
books）：crown皇** ·easybets易**博 ·bet365Bet*** ·weide伟** ·1xbet1xb* ·18bet18b* - 市场（
markets）：eur欧赔 1X2 ·ah亚盘 ·ou大小球 · ah_half 半场亚盘 · ou_half 半场大小球 - 数值口径（
unit字段标明）：eur 为小数赔率；亚盘与大小球为香港水位，换算小数赔率 = 水位 + 1。亚盘line为负表示主队让球；大小球home为大球、away为小球。 - 变动方向：
movement为up涨 /down跌 /steady未变 /none不可比，均以相邻前一点为基准。
响应格式（节选：皇**亚盘 + 易**博欧赔）：
{
"success": true,
"data": {
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"data_age_seconds": 42,
"series_retention_days": 30,
"market_order": ["eur", "ah", "ou"],
"markets": {
"ah": {
"key": "ah",
"label": "亚盘 · 全场让球",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": -0.75,
"phase": "live",
"current": { "home": 0.93, "away": 0.95 },
"previous": { "home": 0.95, "away": 0.93 },
"movement": { "home": "down", "away": "up" }
}
]
},
"eur": {
"key": "eur",
"label": "欧赔 1X2（胜平负）",
"unit": "decimal",
"line_based": false,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": null,
"phase": "live",
"current": { "home": 2.86, "draw": 3.40, "away": 2.45 },
"previous": { "home": 2.87, "draw": 3.38, "away": 2.44 },
"movement": { "home": "down", "draw": "up", "away": "up" }
}
]
}
},
"backup": false
}
}初盘与变动序列：传 series=1 时，每家公司会额外返回opening（真初盘：首次观测到的 home/draw/away 与时刻）与series（观测点数组，每点含 t 秒级时间戳 / line / home / away / draw / phase）。 只想要「初盘 → 当前 → 每次变动」的完整过程与换档点，推荐直接用序列专线/api/open/matches/odds/flow。
已结束比赛的赔率怎么拉：端点与参数完全一致，只要该场仍在保留期（30 天）内就能照常取——终盘水位看/matches/odds/board 或/matches/odds 的current（即终盘），完整变动轨迹看/matches/odds/flow 或/matches/odds?series=1。 注意默认 limit=200 按「行数」截断，只够当前与邻近的观测点，要整场全量明细请显式传limit=2000。 超出 30 天后序列点已清理：/matches/odds/flow 返回404 no_odds_flow，/matches/odds 自动降级为备用源多公司赔率 （source=platform_backup，没有逐点序列），/matches/odds/board 返回available=false；需要更早的历史请在采集期自行落库。
关于半场盘（ah_half / ou_half）：半场亚盘与半场大小球仅由变动流主源（source=platform_flow）提供，主流赛事通常在开赛前 1~3 天开出； 备用赔率源（source=platform_backup，降级时响应带 coverage_note） 不含半场市场；部分小赛事博彩公司全程不开半场盘，此时变动流下 half 市场的 companies 为空（available=false），属上游正常行为而非接口故障。
变动序列专线响应格式（/matches/odds/flow，节选）：
{
"success": true,
"data": {
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"series_retention_days": 30,
"markets": {
"ah": {
"key": "ah",
"label": "亚盘 · 全场让球",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"samples": 128,
"line": -0.75,
"phase": "live",
"first": { "t": 1787582100, "line": -0.5, "home": 0.99, "away": 0.89 },
"current": { "home": 0.93, "away": 0.95 },
"previous": { "home": 0.95, "away": 0.93 },
"movement": { "home": "down", "away": "up" },
"switches": [
{ "t": 1787589741, "from": -0.5, "to": -0.75 }
],
"points": [
{ "t": 1787582100, "line": -0.5, "home": 0.99, "away": 0.89, "phase": "prematch" },
{ "t": 1787589741, "line": -0.75, "home": 0.95, "away": 0.93, "phase": "live" },
{ "t": 1787590120, "line": -0.75, "home": 0.93, "away": 0.95, "phase": "live" }
]
}
]
}
}
}
}phase 阶段过滤：传 phase=prematch 只看赛前盘，phase=live 只看滚球盘（默认 all）。 变动流赛前与滚球共用同一条序列，阶段由开赛时间现推；若该场未记录开赛时间，phase 为null 且不做阶段过滤，请按 null 兼容处理。
水位面板与批量面板 — /api/open/matches/odds/board、/matches/odds/board/batch
盯盘场景推荐用面板接口：仅返回全量公司 × 5 个市场的当前值 + 相邻前一点 + 涨跌方向，载荷 KB 级，适合5~15 秒轮询；批量面板一次可取最多 20 场，服务端整批按「公司 × 市场」一次取数，查询开销与单场同量级。面板不含初盘与序列点（初盘用/matches/odds，变动过程用 /matches/odds/flow）。
批量面板响应格式（节选）：
{
"success": true,
"data": {
"requested": 2,
"returned": 2,
"truncated": false,
"available": 1,
"matches": [
{
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"data_age_seconds": 42,
"market_order": ["eur", "ah", "ou"],
"markets": {
"ou": {
"key": "ou",
"label": "大小球 · 全场",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": 2.5,
"phase": "live",
"current": { "home": 0.90, "away": 0.98 },
"previous": { "home": 0.92, "away": 0.96 },
"movement": { "home": "down", "away": "up" }
}
]
}
}
},
{
"match_id": 67890,
"source": "platform_flow",
"available": false
}
]
}
}接入建议：
- 只想要「现在各家什么水位、涨了还是跌了」→ 用
/matches/odds/board（批量用/board/batch），轮询间隔 5~15 秒。 - 要画走势图、还原初盘口径、或做「几分钟内发生了哪些变动」的检测 → 用
/matches/odds/flow，配合since_minutes只取增量窗口。 - 变动序列保留 30 天，无需本地建库也能回溯；需要长期历史请自行落库。
- 看已结束比赛的赔率：端点不用换，在 30 天保留期内
/matches/odds、/matches/odds/flow、/matches/odds/board都照常返回（current即终盘水位，phase=live为滚球段）；要拿全部变动明细必须显式传limit=2000，默认 200 只返回尾部窗口。超期后 flow 返回404 no_odds_flow，/matches/odds降级为备用源（source=platform_backup，多公司赔率、无逐点序列）。 - 该场变动流暂无数据时（冷门联赛、刚上架），
available=false，可传backup=always让备用赔率源一起返回。
必发指数接口 — /api/open/matches/wom（Weight of Money，必发指数）
返回必发指数（Weight of Money，各市场真实成交资金经上游二次加工的加权分布）数据，覆盖全场/上半场等全时段、全部市场（含大小球各盘口、波胆、角球、红牌等）的资金分布与成交额；随进阶版会员开放、无需另行购买。打开页面时实时拉取最新成交快照（上游随滚球/赛前持续更新）。
响应格式：
{
"success": true,
"data": {
"id": 587703,
"home_team": "NEC Nijmegen",
"away_team": "Bodø/Glimt",
"league": "UEFA Champions League",
"status": "notstarted",
"total_volume": 58184.30,
"money": [
{
"kind": "1X2", // 市场类型（枚举见下方说明）
"line": null, // 盘口线（AH/OU/CORNERS 等带线市场有效，如 2.5/8.5）
"selection": "HOME", // 投注选项：HOME/AWAY/DRAW/OVER/UNDER/YES/NO/比分/组合
"period": "FT", // 时段：FT=全场/1H=上半场/2H=下半场（同一市场分期独立成交）
"name": "Match Odds 1", // 上游市场名
"volume": 12000.50, // 该选项成交额
"market_volume": 30280.00, // 该市场总成交额
"share": 39.63, // 资金占比（%）= volume/market_volume，即必发指数
"league_avg_volume": 80000.00, // 联赛该市场平均成交额（资金热度对比基准）
"price": 2.86, // 当前成交价位（欧盘赔率口径）
"previous_price": 2.87, // 上一价位
"implied_probability": 34.97, // 价位隐含概率（%）= 1/price
"is_live": false, // 是否滚球阶段
"captured_at": "2026-08-19T14:21:00Z" // 数据时间
}
]
}
}市场类型（kind）枚举：1X2=胜平负 OU=大小球（按 line 分盘） AH=亚盘让球 BTTS=双方进球 DNB=不让球（平局退款） DC=双重机会 CS=波胆（正确比分） HTFT=半场/全场 TG=总进球 CORNERS=角球（按 line 分盘） SENDOFF=红牌
解读口径：share 即该选项的必发指数（资金占比）；implied_probability 为价位隐含概率； 两者差值（share − implied）即「冷热偏离」，正数代表资金实际配置高于价格隐含（热门/资金流入），负数代表低于价格隐含（冷门/资金流出）； 某市场内各选项成交并非同时刻，不同盘口（line）为相互独立市场。
金额单位：EUR（欧元）。派生字段：每个 money 条目另含 hot（冷热指数 = share − implied，正=热/负=冷）、pnl（庄家盈亏金额 = market_volume − volume×price，负=该方向若胜出兑付缺口）、pnl_pct（盈亏率 = pnl / market_volume × 100）、payout（市场返还率 = Σvolume / Σ(volume×price) × 100）。热卖(share高)的选项 pnl 为负 —— 资金过热方向若打出庄家即亏，同一判断的两种视角。
资金流变化点接口 — /api/open/matches/wom-history
用于还原一场比赛的资金流过程：不是只看当前快照，而是拿「每次变化」的时间戳与数值。适合绘制资金曲线、做资金异动提醒，或让智能体在赛后转述“什么时间、哪个方向、流入了多少”。
响应格式（已截取单市场示例）：
{
"success": true,
"data": {
"match_id": 601971,
"source": "retained",
"status": "inplay",
"retention_days": 30,
"anomaly_threshold_pp": 5,
"anomaly_change_threshold_pp": 2,
"point_count": 35,
"returned_point_count": 35,
"anomaly_point_count": 3,
"series": {
"1X2_HOME_FT": [
{
"t": "2026-10-07T08:12:30.000Z", // 变化点时间戳
"phase": "live", // prematch / live / postmatch
"key_points": ["latest"], // 关键点模式标记，可同点命中多个
"volume": 1280.40, // 累计成交（EUR）
"volume_delta": 86.20, // 相邻点新增成交（EUR）
"market_volume": 9260.00, // 所属市场累计成交（EUR）
"share": 13.83, // 资金份额（%）
"price": 4.30, // 当前价格
"implied_probability": 23.26, // 价格隐含概率（%）
"divergence": -9.43, // share − implied_probability（百分点）
"is_anomaly": true, // 异动事件
"anomaly_reason": "sharp_divergence_change" // 初始超阈/进入偏离带/偏离快速变化
}
]
}
}
}全量与关键点：不传 limit 即返回完整序列；只要首个记录、开赛前最后赛前记录、最新/终盘记录时，传point=first,last_prematch,latest，返回点会带key_points 标记。增量拉取时用本地最后一个点的t 作为 since，只取新增点。 若只关心异动，直接加 anomaly=1；若只看滚球段，加phase=live。
口径提示：volume 是累计成交，重复求和会放大金额；volume_delta 才是本变化点新增成交。首个点没有前值时volume_delta=null。异动采用事件口径：初始偏离超过 5pp、进入 ±5pp 偏离带，或在带内单点变化至少 2pp；持续停留在偏离带内不会每个点重复标记。异动是市场结构描述，不构成建议。
平台全部 xG 数据均已通过开放 API 提供，按使用场景选择端点：
/matches/prediction → markets.expected_goals.home / away（模型在开赛前生成，开赛后仍返回赛前值）/matches/live → stats.home.xg / stats.away.xg，逐分钟累积曲线在 xg_per_minute（仅进行中比赛）/matches/stats → stats.{home,away}.xg.actual（estimated=true 表示估算值）；批量筛选有 xG 的场次用 /matches/stats/batch?has_xg=true/matches/player-stats → player_stats[].expected_goals / expected_assists；赛季累计用 /trends/player/{player_id} 的 expected_goals/trends/team/{team_id} → expected_goals 趋势序列/matches/shotmap → shots[].xg（射门期望值）与 xgot（射后值，滚球/完赛阶段）status 主状态（查询与返回通用）：notstarted 未开赛 / firsthalf 上半场 / halftime 中场休息 / secondhalf 下半场 / overtime 加时 / inprogress 进行中（滚球总态）/ interrupted 中断 / finished 已完赛 / postponed 推迟 / canceled 取消。 查询聚合值 live 等价于全部进行中状态。
阶段（period）字段命名对照：比赛快照 period = 1st_half / halftime / 2nd_half（与 status 对应）； 必发指数 money[].period = FT 全场 / 1H 上半场 / 2H 下半场； 盘口类数据中的 1T / HT 为「上半场」的缩写变体，语义同 1H。跨端点比对请按语义映射，不要按字符串相等比对；主状态以 status 字段为准。
平台对接中国竞彩官方在售比赛与全部玩法赔率（胜平负/让球胜平负/总进球/半全场/比分），并匹配到平台比赛，供竞彩用户集中查看或 AI 分析。
接口一：在售竞彩聚合 — GET /api/open/jc/matches
全部在售竞彩比赛及玩法赔率，含平台匹配信息。无需 match_id。
{
"success": true,
"data": {
"fetchedAt": "2026-08-20T10:00:00Z",
"updatedAt": "2026-08-20T10:01:20Z",
"total": 32, // 在售总场数（=0 且 dataSource=live 才是「官方当前未开售」）
"matched": 28, // 命中平台比赛数
"dataSource": "live", // live=实时拉取 / cache=新鲜缓存 / stale=上游异常已回退旧数据
"cacheAgeMs": 120000, // 当前数据距今年龄（毫秒），便于判断时效
"upstreamError": null, // 仅 dataSource=stale 时给出上游失败原因
"matches": [
{
"matchup": "日本J联赛", // 竞彩官方联赛名
"matchNo": "周三001",
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"had": {"v": "1.85", "f": 0}, // 胜平负（v=赔率字符串，f=浮动）
"hhad": {"v": "3.20", "f": 0}, // 让球胜平负
"ttg": {"v": "2.10", "f": 0}, // 总进球
"hafu": {"v": "4.00", "f": 0}, // 半全场
"crs": {"v": "8.50", "f": 0}, // 比分
"updateTime": "2026-08-20T09:55:00Z",
"platform": { // 平台匹配（未命中为 null）
"matchId": 213523,
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"eventDate": "2026-08-20T10:00:00Z",
"leagueId": 88,
"status": "notstarted"
}
}
]
}
}接口二：单场竞彩玩法 — GET /api/open/matches/jc
通过平台 match_id 反查该场的全部官方玩法赔率（仅已匹配竞彩的场次有数据）。
{
"success": true,
"data": {
"match": {
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"homeRank": 2,
"awayRank": 5,
"league": "日本J联赛",
"had": {"v": "1.85", "f": 0}, // 胜平负
"hhad": {"v": "3.20", "f": 0}, // 让球胜平负（含让球数）
"ttg": {"v": "2.10", "f": 0}, // 总进球
"hafu": {"v": "4.00", "f": 0}, // 半全场
"crs": {"v": "8.50", "f": 0}, // 比分
"updateTime": "2026-08-20T09:55:00Z",
"sellStatus": "Selling"
}
}
}玩法说明：had=胜平负 hhad=让球胜平负 ttg=总进球 hafu=半全场 crs=比分；赔率统一为 {v, f} 结构，f 为官方浮动标记（0 固定 / 1 升 / -1 降）。
接口三：单场竞彩聚合（含 isports 各公司变动流）— GET /api/open/jc/match
传 jc_match_id（竞彩官方场次ID）获取单场：当前五玩法赔率 + 竞彩官方变动流 + isports 各大公司赔率变动流。未匹配平台的竞彩场次同样可查——这类场次平台无球队基础/高阶数据（platform_match_id 为 null），但仍提供竞彩官方赔率面与 isports 各公司赔率/变动明细。
GET /api/open/jc/match?jc_match_id=2041616&api_key=YOUR_KEY
{
"success": true,
"data": {
"available": true,
"source": "live", // live=当前在售 / history=已下架读留存
"match": {
"match_id": "2041616",
"platform_match_id": null, // 未匹配平台为 null（无平台基础/高阶数据）
"league": "亚运会女足",
"home_team": "中国女足",
"away_team": "菲律宾女足",
"match_num": "1001",
"match_date": "2026-09-21",
"match_time": "15:00:00"
},
"current": { "had": {}, "hhad": {...}, "ttg": {...}, "hafu": {...}, "crs": {...} }, // 当前五玩法赔率 {v,f}
"changes": { "total": 3, "points": [ { "captured_at": "...", "update_time": "...", "odds": {...} } ] }, // 竞彩官方变动流
"diff": { "total": 5, "rows": [ { "time": "...", "market": "hhad", "outcome": "h", "from": "1.80", "to": "1.78" } ] },
"first_vs_current": [ { "market": "hhad", "outcome": "h", "first": "1.80", "current": "1.78" } ],
"isports": { // isports 各公司赔率变动流（未匹配平台场次的主数据面）
"enabled": true,
"matched": true,
"isports_match_id": 261088036, // 匹配到的 isports 场次ID（未匹配为 null，reason 说明原因）
"reason": "cached",
"updated_at": 1789950660, // 上游盘口最后更新时间（秒）
"has_data": true,
"market_types": ["1X2", "AH_2.25", "OU_3", "..."],
"market_type_labels": { "1X2": "欧赔", "AH_2.25": "亚盘 2.25", "OU_3": "大小球 3" },
"companies": [ { "slug": "crown", "name": "皇**" }, { "slug": "macauslot", "name": "澳*" }, ... ],
"odds": {
"1X2": { "crown": { "home": "2.10", "draw": "3.30", "away": "3.40", "home_prematch": "2.05", "home_movement": "up" } },
"AH_2.25":{ "crown": { "line": 2.25, "home_price": "0.95", "away_price": "0.85", "home_prematch": "0.92", "away_movement": "up" } },
"OU_3": { "crown": { "line": 3, "over_price": "0.90", "under_price": "0.90", "over_movement": "down" } }
}
}
}
}变动字段：各公司 odds[市场][公司] 含当前值、初盘值与变动方向（*_movement：up 升 / down 降 / steady 稳）。
竞彩在售模型娱乐预测，仅有效付费正式会员可参加，免费和试用账号不能参赛。使用已绑定账号的 X-API-Key，竞技场不消耗普通数据调用额度。
胜平负、让球胜平负、进球数、比分、大小球、亚盘六个玩法，每条只对应一场比赛、一个玩法、一个方向。每个玩法只能确认一次。
先读取 predictions/targets，按日期及页码浏览比赛，或传 match_id 获取本场 choices。使用 match_id、market（result / handicap_result / total_goals / score / goals / advantage）、selection_id 生成草稿。调用方明确同意后，用 prediction_ids 调用 confirm 确认参赛。
新赛季需重新命名模型、填写必填介绍，并明确选择是否公开每日预测单。仅有效付费正式会员可查看作者已公开的预测。Top3须当月确认预测满20场不同比赛、ROI为正且保持在榜，同场多玩法只计一场；不足20场仍保留过程成绩。连续超过3个已结束的开售日无新确认预测则下榜，连续3个开售日确认新预测后恢复，中断重新计数。
月榜冠军奖励价值649元的旗舰版季卡，亚军奖励两个月旗舰版会员，季军奖励一个月旗舰版会员。
复制完整AI接入指令平台对接中国体育彩票北京单场（北单）在售比赛与全部玩法赔率（让球胜平负/总进球/半全场/比分/上下单双），并匹配到平台比赛，供北单用户集中查看或 AI 分析。北单销售日为 10:00 → 次日 10:00；销售日间隙返回最近销售日的已截止场次（mode=lastSaleDay）。
接口一：在售北单聚合 — GET /api/open/bd/matches
全部在售北单比赛及玩法赔率，含平台匹配信息。无需参数。
{
"success": true,
"data": {
"updatedAt": "2026-09-27 09:45:00", // 赔率最新更新时间
"total": 32, // 在售总场数（=0 且 dataSource=live 才是「官方当前未开售」）
"matched": 28, // 命中平台比赛数
"dataSource": "cache", // live=实时拉取 / cache=新鲜缓存 / stale=上游异常已回退旧数据
"mode": "live", // live=当前在售 / lastSaleDay=销售日间隙回退最近销售日（均已截止）
"cacheAgeMs": 120000,
"matches": [
{
"matchId": "bd2041616", // 北单场次ID（用于 /bd/match 查单场）
"vfootballMatchId": 223067, // 平台比赛ID（未匹配为 null，可直接查 /matches/detail）
"matchNum": "26", // 北单场次号
"league": "意大利甲级联赛",
"homeTeam": "罗马",
"awayTeam": "佛罗伦萨",
"goalLine": "-1", // 让球数（正=主队受让，负=主队让球）
"wdl": { "h": {"v":"1.85","f":0}, "d": {"v":"3.40","f":0}, "a": {"v":"4.20","f":0} }, // 让球胜平负
"ttg": { "s0": {"v":"8.5","f":0}, "s1": {"v":"4.3","f":0} /* s0~s7，s7=7球及以上 */ },
"hafu": { "hh": {"v":"3.2","f":0} /* hh/ha/hd/ah/aa/ad/dh/da/dd 九项 */ },
"crs": { "s10": {"v":"6.5","f":0} /* 比分 25 档 */ },
"uo": { "us": {"v":"1.9","f":0}, "ud": {"v":"1.9","f":0}, "ds": {"v":"1.9","f":0}, "dd": {"v":"1.9","f":0} }, // 上下单双（北单特有）
"score": null, // 彩果：全场比分（未开奖为 null）
"result": null, // 彩果：让球胜平负结果
"sellStatus": 1, // 1=在售 0=停售
"platform": { "matchId": 223067, "homeTeam": "Roma", "awayTeam": "Fiorentina",
"eventDate": "2026-09-27T18:30:00Z", "leagueId": 1, "status": "notstarted" }
}
]
}
}接口二：单场北单详情 — GET /api/open/bd/match
传 bd_match_id（bd+数字）获取单场全部玩法赔率与销售状态；当前赛程优先，场次翻页或停售后自动回退 7 天本地历史留存（source=history）。
GET /api/open/bd/match?bd_match_id=bd2041616&api_key=YOUR_KEY
{
"success": true,
"data": {
"available": true,
"source": "live", // live=当前在售赛程 / history=读 7 天本地留存
"provider": "okooo",
"match": { "matchId": "bd2041616", "matchNum": "26", "league": "意大利甲级联赛",
"homeTeam": "罗马", "awayTeam": "佛罗伦萨", "goalLine": "-1",
"wdl": {...}, "ttg": {...}, "hafu": {...}, "crs": {...}, "uo": {...},
"updateTime": "2026-09-27 09:45:00", "sellStatus": 1 }
}
}接口三：单场北单玩法（平台比赛反查）— GET /api/open/matches/bd
通过平台 match_id 反查该场的北单玩法赔率（仅已匹配北单的场次有数据；未匹配时 matched=false 并带 reason）。
GET /api/open/matches/bd?match_id=223067&api_key=YOUR_KEY
{
"success": true,
"data": {
"matched": true,
"match": { "matchId": "bd2041616", "homeTeam": "罗马", "awayTeam": "佛罗伦萨",
"goalLine": "-1", "wdl": {...}, "ttg": {...}, "hafu": {...},
"crs": {...}, "uo": {...}, "updateTime": "2026-09-27 09:45:00" }
}
}玩法说明：wdl=让球胜平负 ttg=总进球 hafu=半全场 crs=比分 uo=上下单双（北单特有）；赔率统一为 {v, f} 结构，v 为 “-” 表示该项未开售，f 为浮动标记。
您的 AI 智能体可通过 API Key 直接调用 V球数据接口，获取实时足球数据进行分析。
复制场景提示词（12 条精品模板）步骤一：获取 API Key
在 V球数据平台注册账号并登录后，此处将自动显示您的专属 API Key。
步骤二：配置智能体
在您的 AI 智能体（如 Codex、扣子、WorkBuddy、豆包、Zcode、DeepSeek、智谱清言、Kimi 等平台，或自定义 Agent）中，添加 HTTP 工具或 Function Calling， 配置请求头 X-API-Key， 指向对应的数据接口即可。
步骤三：调用数据
智能体可根据用户提问，自动调用相应的接口获取比赛详情、赔率、统计、历史交锋等数据， 结合大模型能力生成分析报告。
💡 推荐组合接口
对于赛前分析场景，建议同时调用：matches/detail + matches/odds + matches/odds/flow + matches/h2h + teams/fixtures
加入支持群
购买激活码 / API Key / 技术支持 · QQ群 816477623
加群验证码 403039