# 高校志愿录取机会与梯度评估模型
> 来源页面: https://www.gugudata.com/api/details/admission-predict
## 概览
- API 标识: `admission-predict`
- 分类: 教育/高考
- 描述: 基于历史招生条件评估高校志愿机会与梯度
- 标签: AI预测 / 高考志愿 / 录取概率
- 短标签: AI / 高考 / 高等教育
- 详情页: https://www.gugudata.com/api/details/admission-predict
- LLM Markdown: https://www.gugudata.com/api/details/admission-predict/llm.md
- 数据预览: https://www.gugudata.com/preview/admission-predict
- 购买开通: https://www.gugudata.com/order/admission-predict
- APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders
## 给大模型的接入指令
如果你正在帮助用户接入这个 API，请优先使用本文档中的接口地址、请求方式、请求参数、返回参数、状态码、cURL 示例和预览数据生成代码或排查问题。
- 接入目标: 调用 `高校志愿录取机会与梯度评估模型`，不要臆造未在文档中出现的参数或返回字段。
- AppKey 获取: 用户登录咕咕数据开发者中心后，在 `APP KEY 管理` 页面复制对应产品的 AppKey。
- AppKey 替换: 示例中的 `YOUR_APPKEY`、`APPKEY`、`{{YOUR_APPKEY}}`、`{{appkey}}`、`{{appKey}}` 都应替换为用户自己的 AppKey。
- AppKey 传递: 推荐使用 `AppKey` 请求头；历史 query 参数 `appkey` 继续兼容。
- 开通与续费: 未开通时引导用户访问购买开通页；已开通或需要续费时，引导用户进入开发者中心或订单与续费页。
- 错误处理: HTTP 状态码代表传输层结果，响应体内的业务状态码代表接口业务结果，代码中应分别处理。
- 生产建议: AppKey 应保存在服务端环境变量或密钥配置中，由服务端统一发起请求，不要写入网页、App 客户端或公开仓库。
关键链接:
- 接口详情页: https://www.gugudata.com/api/details/admission-predict
- LLM Markdown: https://www.gugudata.com/api/details/admission-predict/llm.md
- 数据预览: https://www.gugudata.com/preview/admission-predict
- 购买开通页: https://www.gugudata.com/order/admission-predict
- 开发者中心 APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders
## API 功能
- 输入考生省份、科类和成绩，整理同类考试条件下的高校志愿参考；
- 按目标高校名称名单评估，便于核对关注院校的机会分；
- 支持使用高校唯一 ID 关联院校基础信息与评估对象；
- 按高校所在地省份筛选，整理目标地区的院校候选；
- 可启用本省优先，调整符合条件院校的推荐顺序；
- 使用 Top-N 控制返回院校数量，整理不同长度的志愿候选清单；
- 按自定义概率区间和每档数量整理多档志愿梯度；
- 提供概率、院校排名和综合策略三种档内排序方式；
- 支持专业级参考，资料不足时标明采用院校整体资料的参考结果；
- 提供录取参考概率、机会分与梯度解释，辅助人工比较院校；
- 展示实际使用的历史年份、分差及可用的招生计划覆盖依据；
- 返回证据一致性状态，帮助核对解释与结构化结果是否对应；
- 默认最大 QPS:5，可在开发者中心自助升级，年付订单接口调用次数不限。
- [接口调用状态与状态监控](https://www.gugudata.com/status)
## API 文档
- 接口地址: `https://api.gugudata.com/ai/admission/predict`
- 返回格式: `application/json; charset=utf-8`
- 请求方式: `POST`
- 请求协议: `HTTPS`
- 请求示例: `https://api.gugudata.com/ai/admission/predict`
- 接口测试: https://api.gugudata.com/ai/admission/predict/demo
- Apifox: https://doc.gugudata.com/
- Postman: https://www.postman.com/gugudata/gugudata-official
- OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json
## 鉴权方式
接口支持以下 AppKey 传递方式，任选一种即可；已有请求示例、Postman 集合和历史代码仍可继续使用原来的 `appkey` 参数方式。
| 传输载体 | 参数 | 示例 | 说明 |
| --- | --- | --- | --- |
| HTTP Header | `AppKey` | `AppKey: YOUR_APPKEY` | 推荐方式，适合服务端接入和统一封装。 |
| HTTP Header | `X-GUGUDATA-APPKEY` | `X-GUGUDATA-APPKEY: YOUR_APPKEY` | 兼容已有客户端的 Header 名称。 |
| HTTP Header | `X-API-Key` | `X-API-Key: YOUR_APPKEY` | 通用 API Key Header，便于和常见 API 客户端集成。 |
| HTTP Header | `Authorization` | `Authorization: Bearer YOUR_APPKEY` | 适合 OpenAI 兼容接口或 Bearer Token 风格客户端。 |
| Query 参数 | `appkey` | `?appkey=YOUR_APPKEY` | 兼容现有示例、Postman 集合、浏览器调试和历史代码。 |
> 部分历史 POST 接口仍兼容表单或 JSON body 中的 `appkey`；新接入建议优先使用 Header 或 Query 参数。
## 请求参数
| 参数名 | 参数类型 | 是否必须 | 默认值 | 备注 |
| --- | --- | --- | --- | --- |
| appkey | string | 是 | 无 | 付费后获取的 APPKEY。支持 AppKey、X-GUGUDATA-APPKEY、X-API-Key 请求头、Bearer、Query 和历史 JSON 鉴权字段；多处一致凭据允许，重复或冲突凭据失败。 |
| province | string | 是 | 无 | 考生所在省份，与历年分数线数据保持一致 |
| subject_type | string | 是 | 无 | 科类/选科：理科、文科、物理类、历史类、综合等 |
| score | number | 否 | 无 | 考生裸分，与 rank 至少提供一项；一般省份 0–750，海南最高 900。仅位次请求是否可评估取决于当前模型与分段位次资料，无法换算时返回明确无数据原因。 |
| rank | integer | 否 | 无 | 考生全省位次，与 score 至少提供一项。保留该历史参数；当前模型未采用位次时以 meta.rank_source、effective_rank 说明，不将传入位次视为已参与计算。 |
| batch | string | 否 | 本科批 | 报考批次，目前支持普通本科批次 |
| top_n | integer | 否 | 50 | 返回院校数量上限，范围 1-200；传入 probability_tiers 时按各档位数量返回 |
| probability_tiers | array | 否 | 无，不传时使用 top_n | 概率分层配置，仅支持 JSON Body 传入。示例：[{"name":"safe","label":"保","min_probability":0.98,"limit":3},{"name":"stable","label":"稳","min_probability":0.8,"limit":3},{"name":"reach","label":"冲","min_probability":0.75,"limit":3}]。每项包含 name、label、min_probability、limit；min_probability 必须严格递减，相邻档位自动形成概率区间；可配合 tier_sort 控制每档内部取数顺序，用于一次返回保、稳、冲等多档志愿结果；不传时继续按 top_n 返回。 |
| tier_sort | string | 否 | probability | 概率分层每档内部排序策略，仅在 probability_tiers 生效时使用；可选 probability、college_rank、balanced。probability 按录取概率排序，college_rank 按院校排名优先，balanced 综合院校层次、排名和概率。 |
| include_explanation | boolean | 否 | false | 是否返回补充影响因素说明，默认关闭以控制响应时延，开启后仅对部分结果返回解释信息 |
| prefer_local | boolean | 否 | false | 是否在排序时优先本省院校 |
| college_provinces | array | 否 | 无 | 按院校所在省份过滤，留空则不过滤；Query 方式可多次传值，格式 ["江苏", "上海"] |
| target_colleges | array | 否 | 无 | 指定院校名单，仅对名单内院校预测 |
| uuid | string | 否 | 无 | 指定一个院校唯一 ID，仅对该院校预测；可使用全国大学高校基础信息接口返回的 SchoolUUID |
| target_college_uuids | array | 否 | 无 | 指定院校唯一 ID 列表，仅对名单内院校预测；多个值可使用数组或逗号分隔字符串 |
| year | integer | 否 | 当前配置预测周期 | 目标招生年份，当前配置预测周期为 2026；兼容保留传入值，实际预测周期以 meta.prediction_year 和 requested_year/effective_year 为准，不提供历史回测语义。 |
| major_name | string | 否 | 无 | 专业名称（用于专业级预测），命中专业样本时优先返回该专业结果；若样本不足，系统可能切换到院校层或其他兼容预测路径 |
| local_batch_name | string | 否 | 无 | 本地批次名称（用于过滤），不提供时默认使用 batch 参数的值 |
## 返回参数
| 参数名 | 参数类型 | 备注 |
| --- | --- | --- |
| DataStatus.StatusCode | integer | 接口状态码，100 表示成功 |
| DataStatus.StatusDescription | string | 接口返回状态说明 |
| DataStatus.ResponseDateTime | string | 返回时间 |
| DataStatus.DataTotalCount | integer | 本次返回院校数量 |
| Data.predictions | array | 预测结果列表 |
| Data.predictions[].college_name | string | 院校名称 |
| Data.predictions[].admission_probability | number | 兼容字段：历史条件下的录取参考概率（0-1），永久保留以兼容现有客户 |
| Data.predictions[].chance_score | number | 推荐使用字段：历史条件机会分（0-1），与 admission_probability 数值完全相同 |
| Data.predictions[].recommendation | string | 兼容字段：保留现有摘要文案和值，现有客户无需修改；新应用建议使用 interpretation |
| Data.predictions[].long_recommendation | string | 兼容字段：保留现有长文案和值；新应用建议使用可复算的 long_interpretation |
| Data.predictions[].interpretation | string | 推荐使用字段：按固定机会区间返回的志愿梯度解释 |
| Data.predictions[].long_interpretation | string | 推荐使用字段：只使用同一响应中的结构化证据拼装；证据不足时省略对应句子，证据冲突时停止输出详细数字 |
| Data.predictions[].historical_years | array | 该结果实际使用的历史招生年份；不会根据截至年份和数量推测连续年份 |
| Data.predictions[].data_through_year | integer | 该结果实际使用的最新历史招生年份 |
| Data.predictions[].plan_coverage | object | 招生计划覆盖信息；AVAILABLE 时 ratio 可由 covered_plan_total / school_plan_total 复算，未知不会用 0 表示 |
| Data.predictions[].fallback_path | object | 请求层级、实际数据层级、兼容策略和原因码 |
| Data.predictions[].evidence_consistency_status | string | 证据复算状态：VERIFIED、PARTIAL 或 FAILED |
| Data.predictions[].evidence | object | 关键证据对象；保留 recent_3y_min_score，并新增具名 historical_score_summary 供年份、最低线、输入分数和分差复算 |
| Data.predictions[].evidence.historical_score_summary | object | 具名历史分数摘要，包含 years、latest_min_score、recent_min_score_average、student_score、gap_to_latest_min 和 gap_to_recent_min_average |
| Data.predictions[].shap_explanation | object | 补充影响因素说明，仅在 include_explanation=true 且当前结果可解释时返回 |
| Data.predictions[].major_name | string | 命中专业级预测时返回对应专业名称；若结果回退到院校层，则该字段可能为空 |
| Data.predictions[].tier_name | string | 命中的概率档位标识，仅在请求 probability_tiers 时返回 |
| Data.predictions[].tier_label | string | 命中的概率档位展示名称，仅在请求 probability_tiers 时返回 |
| Data.predictions[].tier_min_probability | number | 命中档位的录取概率下限，仅在请求 probability_tiers 时返回；下一档会自动以上一档下限作为概率上界 |
| Data.meta.total_colleges | integer | 返回院校数量 |
| Data.meta.student_score | number | 考生分数 |
| Data.meta.student_province | string | 考生省份 |
| Data.meta.local_colleges | integer | 结果中同省院校数量，无 is_local 字段时为 null |
| Data.meta.score_diff_min | number | 分差绝对值最小值 |
| Data.meta.score_diff_median | number | 分差绝对值中位数，用于梯度判断 |
| Data.meta.prefer_local | boolean | 是否启用本省优先排序 |
| Data.meta.college_provinces | array | 请求中用于过滤院校省份的列表 |
| Data.meta.model_version | string | 模型版本号 |
| Data.meta.data_through_year | integer | 本次返回结果实际使用的最新历史招生年份 |
| Data.meta.historical_years | array | 本次返回结果实际使用的历史招生年份并集 |
| Data.meta.coverage_level | string | 本次结果的历史数据覆盖等级；结果层级不一致时为 mixed |
| Data.meta.interpretation_policy_version | string | 机会与梯度解释策略版本 |
| Data.meta.policy_constraints | object | 请求级政策评估边界，列出已评估项、未评估项及核对提示 |
| Data.meta.probability_tiers | array | 概率分层返回统计，仅在请求 probability_tiers 时返回；每项包含 name、label、min_probability、limit、returned_count，下一档会自动以上一档下限作为概率上界 |
| Data.meta.tier_sort | string | 本次概率分层每档内部排序策略，仅在请求 probability_tiers 时返回 |
| Data.meta.fallback.applied | boolean | 是否启用了 fallback 或补充预测策略 |
| Data.meta.fallback.strategy | string | fallback 策略标识，用于说明当前结果采用的兼容预测路径 |
| Data.meta.fallback.requested_year | integer | 请求中传入的目标预测年份 |
| Data.meta.fallback.effective_year | integer | 实际用于匹配分数线或历史样本的有效年份 |
| Data.meta.fallback.requested_major_name | string | 请求中传入的专业名称 |
| Data.meta.fallback.effective_major_name | string | 实际命中的参考专业名称；若未命中稳定专业样本则为空 |
| Data.meta.fallback.reason | string | 采用兼容预测路径时返回稳定原因码；未采用时为空 |
| Data.disclaimer | string | 免责声明 |
| DataStatus.RequestParameter | string | 实际业务参数，不包含凭据。 |
| DataStatus.RequestId | string | 本次请求的关联标识。 |
| DataStatus.NoDataReason | string | 有效请求无可评估结果时返回稳定原因；有结果时省略。 |
| Data.meta.requested_year | integer | 请求中传入的年份。 |
| Data.meta.prediction_year | integer | 当前实际模型预测周期。 |
| Data.meta.rank_source | string | 实际位次来源；missing 表示本次模型没有采用可用位次。 |
| Data.meta.effective_rank | integer | 实际参与评估的位次；未采用时为 null。 |
## 响应示例（真实数据节选）
```json
{
"DataStatus": {
"RequestParameter": "{\"province\": \"江苏\", \"subject_type\": \"物理类\", \"score\": 635, \"rank\": 12000, \"batch\": \"本科批\", \"top_n\": 10, \"include_explanation\": false, \"prefer_local\": false, \"college_provinces\": [\"江苏\", \"上海\"], \"target_colleges\": [\"南京大学\", \"东南大学\", \"南京航空航天大学\", \"南京理工大学\", \"苏州大学\", \"南京邮电大学\", \"河海大学\", \"江南大学\", \"上海大学\", \"华东理工大学\"], \"year\": 2026, \"local_batch_name\": \"本科批\"}",
"StatusCode": 100,
"StatusDescription": "预测成功",
"ResponseDateTime": "2026-10-15 11:40:31.437",
"DataTotalCount": 10,
"RequestId": "4c034183-8a67-4b2e-b2fe-730f49b66c54"
},
"Data": {
"predictions": [
{
"college_name": "苏州大学",
"admission_probability": 0.9890046296296297,
"evidence": {
"recent_3y_min_score": [
600.0,
598.0
],
"score_gap": 36.40000000000009,
"score_gap_original": 35.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 42,
"plan_enrollment": 3111,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 34888.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": 3.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 600.0,
"recent_min_score_average": 598.0,
"student_score": 635.0,
"gap_to_latest_min": 35.0,
"gap_to_recent_min_average": 37.0
}
},
"shap_explanation": null,
"recommendation": "录取概率高",
"long_recommendation": "当前录取参考概率较高，按近年录取情况看，你的分数处于相对安全区间。你的分数高于近三年最低线35分，也高于近三年均值线37分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "保",
"risk_policy_version": "legacy-v1",
"chance_score": 0.9890046296296297,
"interpretation": "历史条件下机会较高，建议作为稳妥梯度参考。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.99 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 35 分，高于近年最低线均值 37 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "江南大学",
"admission_probability": 0.9865689865689866,
"evidence": {
"recent_3y_min_score": [
604.0,
601.0
],
"score_gap": 33.10000000000002,
"score_gap_original": 31.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 57,
"plan_enrollment": 837,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 31362.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": 3.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 604.0,
"recent_min_score_average": 601.0,
"student_score": 635.0,
"gap_to_latest_min": 31.0,
"gap_to_recent_min_average": 34.0
}
},
"shap_explanation": null,
"recommendation": "录取概率高",
"long_recommendation": "当前录取参考概率较高，按近年录取情况看，你的分数处于相对安全区间。你的分数高于近三年最低线31分，也高于近三年均值线34分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "保",
"risk_policy_version": "legacy-v1",
"chance_score": 0.9865689865689866,
"interpretation": "历史条件下机会较高，建议作为稳妥梯度参考。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.99 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 31 分，高于近年最低线均值 34 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "南京邮电大学",
"admission_probability": 0.9640883977900553,
"evidence": {
"recent_3y_min_score": [
608.0,
608.3333333333334
],
"score_gap": 26.76666666666665,
"score_gap_original": 27.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": false,
"is_dual_class": true,
"college_rank": 122,
"plan_enrollment": 3368,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 27965.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": -5.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 608.0,
"recent_min_score_average": 608.3333333333334,
"student_score": 635.0,
"gap_to_latest_min": 27.0,
"gap_to_recent_min_average": 26.66666666666663
}
},
"shap_explanation": null,
"recommendation": "录取概率高",
"long_recommendation": "当前录取参考概率较高，按近年录取情况看，你的分数处于相对安全区间。你的分数高于近三年最低线27分，也高于近三年均值线26.7分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "保",
"risk_policy_version": "legacy-v1",
"chance_score": 0.9640883977900553,
"interpretation": "历史条件下机会较高，建议作为稳妥梯度参考。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.96 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 27 分，高于近年最低线均值 26.7 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "华东理工大学",
"admission_probability": 0.7938192601841736,
"evidence": {
"recent_3y_min_score": [
620.0,
624.0
],
"score_gap": 12.200000000000045,
"score_gap_original": 15.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 38,
"plan_enrollment": 236,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 19004.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": false,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": -10.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 620.0,
"recent_min_score_average": 624.0,
"student_score": 635.0,
"gap_to_latest_min": 15.0,
"gap_to_recent_min_average": 11.0
}
},
"shap_explanation": null,
"recommendation": "需要注意梯度，但成功率较高",
"long_recommendation": "当前录取参考概率中等偏高，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线15分，也高于近三年均值线11分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "稳",
"risk_policy_version": "legacy-v1",
"chance_score": 0.7938192601841736,
"interpretation": "历史条件下机会中等偏高，建议结合其他志愿形成合理梯度。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.79 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 15 分，高于近年最低线均值 11 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "河海大学",
"admission_probability": 0.7594263939029284,
"evidence": {
"recent_3y_min_score": [
626.0,
620.6666666666666
],
"score_gap": 12.733333333333348,
"score_gap_original": 9.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 65,
"plan_enrollment": 1009,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 15099.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": 13.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 626.0,
"recent_min_score_average": 620.6666666666666,
"student_score": 635.0,
"gap_to_latest_min": 9.0,
"gap_to_recent_min_average": 14.333333333333371
}
},
"shap_explanation": null,
"recommendation": "需要注意梯度，但成功率较高",
"long_recommendation": "当前录取参考概率中等偏高，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线9分，也高于近三年均值线14.3分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "稳",
"risk_policy_version": "legacy-v1",
"chance_score": 0.7594263939029284,
"interpretation": "历史条件下机会中等偏高，建议结合其他志愿形成合理梯度。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.76 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 9 分，高于近年最低线均值 14.3 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "上海大学",
"admission_probability": 0.6437263115898662,
"evidence": {
"recent_3y_min_score": [
629.0,
629.3333333333334
],
"score_gap": 5.7666666666666515,
"score_gap_original": 6.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 67,
"plan_enrollment": 126,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 13359.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": false,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": -3.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 629.0,
"recent_min_score_average": 629.3333333333334,
"student_score": 635.0,
"gap_to_latest_min": 6.0,
"gap_to_recent_min_average": 5.666666666666629
}
},
"shap_explanation": null,
"recommendation": "需要注意梯度，但成功率较高",
"long_recommendation": "当前录取参考概率中等偏高，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线6分，也高于近三年均值线5.7分。本次按院校层历史录取数据估算。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "稳",
"risk_policy_version": "legacy-v1",
"chance_score": 0.6437263115898662,
"interpretation": "历史条件下机会中等偏高，建议结合其他志愿形成合理梯度。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.64 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数高于最新可用最低线 6 分，高于近年最低线均值 5.7 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "南京理工大学",
"admission_probability": 0.36543654365436545,
"evidence": {
"recent_3y_min_score": [
639.0,
635.0
],
"score_gap": -1.2000000000000455,
"score_gap_original": -4.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 37,
"plan_enrollment": 633,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 8362.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": 7.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 639.0,
"recent_min_score_average": 635.0,
"student_score": 635.0,
"gap_to_latest_min": -4.0,
"gap_to_recent_min_average": 0.0
}
},
"shap_explanation": null,
"recommendation": "录取概率低",
"long_recommendation": "当前录取参考概率较低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低4分，但仍高于近三年均值线0分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。本次按院校层历史录取数据估算。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "高风险",
"risk_policy_version": "legacy-v1",
"chance_score": 0.36543654365436545,
"interpretation": "历史条件下机会偏低，建议仅作为冲刺梯度参考。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.37 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数低于最新可用最低线 4 分，高于近年最低线均值 0 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "南京航空航天大学",
"admission_probability": 0.3329758074127041,
"evidence": {
"recent_3y_min_score": [
645.0,
643.6666666666666
],
"score_gap": -9.066666666666606,
"score_gap_original": -10.0,
"province_line_gap": 172.0,
"is_985": false,
"is_211": true,
"is_dual_class": true,
"college_rank": 47,
"plan_enrollment": 633,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 5985.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": 2.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 645.0,
"recent_min_score_average": 643.6666666666666,
"student_score": 635.0,
"gap_to_latest_min": -10.0,
"gap_to_recent_min_average": -8.666666666666629
}
},
"shap_explanation": null,
"recommendation": "录取概率低",
"long_recommendation": "当前录取参考概率较低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低10分，也比近三年均值线低8.7分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。本次按院校层历史录取数据估算。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "高风险",
"risk_policy_version": "legacy-v1",
"chance_score": 0.3329758074127041,
"interpretation": "历史条件下机会较低，建议谨慎填报并补充更稳妥志愿。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.33 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数低于最新可用最低线 10 分，低于近年最低线均值 8.7 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "东南大学",
"admission_probability": 0.25676378772112385,
"evidence": {
"recent_3y_min_score": [
644.0,
645.6666666666666
],
"score_gap": -10.166666666666515,
"score_gap_original": -9.0,
"province_line_gap": 172.0,
"is_985": true,
"is_211": true,
"is_dual_class": true,
"college_rank": 20,
"plan_enrollment": 844,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 6362.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": -3.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 644.0,
"recent_min_score_average": 645.6666666666666,
"student_score": 635.0,
"gap_to_latest_min": -9.0,
"gap_to_recent_min_average": -10.666666666666629
}
},
"shap_explanation": null,
"recommendation": "录取概率低",
"long_recommendation": "当前录取参考概率较低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低9分，也比近三年均值线低10.7分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。本次按院校层历史录取数据估算。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "高风险",
"risk_policy_version": "legacy-v1",
"chance_score": 0.25676378772112385,
"interpretation": "历史条件下机会较低，建议谨慎填报并补充更稳妥志愿。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.26 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数低于最新可用最低线 9 分，低于近年最低线均值 10.7 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
},
{
"college_name": "南京大学",
"admission_probability": 0.14505624629958558,
"evidence": {
"recent_3y_min_score": [
658.0,
661.0
],
"score_gap": -25.100000000000023,
"score_gap_original": -23.0,
"province_line_gap": 172.0,
"is_985": true,
"is_211": true,
"is_dual_class": true,
"college_rank": 6,
"plan_enrollment": 753,
"plan_coverage_ratio": 1.0,
"student_rank": null,
"historical_min_rank": 2414.0,
"rank_gap": 0.0,
"rank_ratio": 0.0,
"rank_missing": true,
"rank_source": "missing",
"rank_data_year": null,
"score_source": "request",
"score_data_year": null,
"is_local": true,
"history_year_count": 3,
"control_line_source": "historical_admission_line",
"control_line_year": null,
"recent_min_trend": -6.0,
"probability_source": "binary_college_fallback",
"aggregation_mode": "college_fallback",
"historical_score_summary": {
"years": [
2023,
2024,
2025
],
"latest_min_score": 658.0,
"recent_min_score_average": 661.0,
"student_score": 635.0,
"gap_to_latest_min": -23.0,
"gap_to_recent_min_average": -26.0
}
},
"shap_explanation": null,
"recommendation": "录取概率低",
"long_recommendation": "当前录取参考概率较低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低23分，也比近三年均值线低26分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。本次按院校层历史录取数据估算。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
"major_name": null,
"tier_name": null,
"tier_label": null,
"tier_min_probability": null,
"education_level": "bachelor",
"coverage_level": "full",
"data_through_year": 2025,
"risk_label": "高风险",
"risk_policy_version": "legacy-v1",
"chance_score": 0.14505624629958558,
"interpretation": "历史条件下机会较低，建议谨慎填报并补充更稳妥志愿。",
"long_interpretation": "在江苏、物理类、本科批和院校历史数据范围内，模型给出 0.15 的历史条件机会估计。历史数据覆盖 2023 至 2025 年。输入分数低于最新可用最低线 23 分，低于近年最低线均值 26 分。仍需核对当年专业组、选科、体检、校区和调剂要求。",
"historical_years": [
2023,
2024,
2025
],
"plan_coverage": {
"status": "NOT_APPLICABLE",
"ratio": null,
"matched_plan_rows": null,
"covered_plan_total": null,
"school_plan_total": null
},
"fallback_path": {
"applied": false,
"requested_level": "college",
"effective_level": "college",
"strategy": "college_fallback",
"reason": null
},
"evidence_consistency_status": "VERIFIED"
}
],
"meta": {
"total_colleges": 10,
"student_score": 635.0,
"student_province": "江苏",
"local_colleges": 8,
"score_diff_min": 4.0,
"score_diff_median": 12.5,
"prefer_local": false,
"college_provinces": [
"江苏",
"上海"
],
"model_version": "v1.1.0",
"prediction_year": 2026,
"requested_year": 2026,
"history_through_year": 2025,
"data_through_year": 2025,
"historical_years": [
2023,
2024,
2025
],
"interpretation_policy_version": "2026-08",
"policy_constraints": {
"status": "PARTIALLY_EVALUATED",
"evaluated": [
"province",
"subject_type",
"batch"
],
"not_evaluated": [
"subject_selection",
"physical_exam",
"single_subject_score",
"campus",
"tuition",
"transfer_policy"
],
"notice": "未评估项需以当年省级考试院和院校招生章程为准。"
},
"education_level": "bachelor",
"coverage_level": "full",
"risk_policy_version": "legacy-v1",
"candidate_pool": {
"total_colleges": 10,
"feature_rows": 10
},
"rank_source": "missing",
"rank_missing": true,
"effective_rank": null,
"student_rank": null,
"score_source": "request",
"score_data_year": null,
"effective_score": 635.0,
"score_segments_through_year": null,
"control_line_source": "historical_admission_line",
"control_lines_through_year": null,
"data_sources_through_year": {
"admission_lines": 2025,
"major_admission_lines": null,
"enrollment_plans": 2026,
"province_control_lines": null,
"score_segments": null
},
"fallback": {
"applied": false,
"strategy": null,
"requested_year": 2026,
"effective_year": 2026,
"requested_major_name": null,
"effective_major_name": null,
"reason": null
}
},
"disclaimer": "本预测结果综合历年真实招生数据、院校录取趋势与机器学习模型推算而成，仅供志愿填报参考。建议结合当年政策、院校最新官方信息及个人实际情况综合判断，最终录取结果以各省考试院和院校官方公布为准。"
}
}
```
## 相关接口
### 专业录取线按录取概率排序
- 请求方式: `POST`
- 资源路径: `/ai/admission/major-line-rank?appkey={{appkey}}`
- 接口地址: `https://api.gugudata.com/ai/admission/major-line-rank?appkey=YOUR_APPKEY`
- 描述: 先查询历年高考专业录取分数线候选集，再结合录取概率预测结果排序返回，适合按省份、科类和分数筛选专业线后做志愿梯度参考
#### 请求参数
| 参数名 | 参数类型 | 是否必须 | 备注 |
| --- | --- | --- | --- |
| appkey | string | 是 | 付费后获取的 APPKEY，可通过 Query (?appkey=) 或 JSON Body 提供 |
| province | string | 是 | 考生所在省份，对应专业录取线的 enrollProvince |
| subject_type | string | 是 | 科类/选科，对应专业录取线的 typeName，例如 物理类、历史类、理科、文科、综合 |
| score | number | 是 | 考生裸分（0-750），用于计算专业线候选项的录取概率 |
| rank | integer | 否 | 考生全省位次，可为空 |
| batch | string | 否 | 报考批次，默认 本科批，对应专业录取线的 batchName |
| year | integer | 否 | 预测年份，默认与 line_year 保持一致 |
| line_year | integer | 否 | 专业录取线年份，默认使用 year |
| major_name | string | 否 | 专业名称过滤条件 |
| school_name | string | 否 | 院校名称过滤条件 |
| uuid | string | 否 | 院校唯一 ID，可用于限定单个院校 |
| schooluuid | string | 否 | 院校唯一 ID，等同于 uuid |
| target_college_uuids | array | 否 | 院校唯一 ID 列表，可用于限定多个院校 |
| subject_selection | string | 否 | 选科要求过滤条件，对应专业录取线的 subjectSelection |
| min_score | integer | 否 | 录取最低分小于等于该值的过滤条件 |
| minrange | string | 否 | 录取最低分区间，格式如 500,700 |
| score_window | integer | 否 | 省份宽查询时围绕考生成绩自动生成候选分数区间，默认 60，传 0 可关闭 |
| sort | string | 否 | 专业线候选集原始排序条件 |
| probability_sort | string | 否 | 录取概率排序方向，支持 desc 或 asc，默认 desc |
| page_index | integer | 否 | 排序后页码，从 1 开始，默认 1 |
| page_size | integer | 否 | 排序后每页数量，默认 10，最大 50 |
| candidate_limit | integer | 否 | 最多参与预测排序的专业线候选数量，默认 30，最大 50 |
| major_name_strict | boolean | 否 | 专业名称是否严格匹配，默认 false |
| exclude_major_category | boolean | 否 | 是否过滤专业大类记录，默认 true |
| include_prediction_evidence | boolean | 否 | 是否返回模型证据字段，默认 false |
#### 请求示例
```json
{
"method": "POST",
"url": "https://api.gugudata.com/ai/admission/major-line-rank?appkey=YOUR_APPKEY",
"content_type": "application/json",
"body": {
"province": "河北",
"subject_type": "物理类",
"score": 591,
"rank": 8190,
"batch": "本科批",
"line_year": 2025,
"year": 2026,
"page_size": 10,
"candidate_limit": 30,
"probability_sort": "desc"
}
}
```
#### 返回参数
| 参数名 | 参数类型 | 备注 |
| --- | --- | --- |
| Data.items | array | 排序后的专业录取线结果列表 |
| Data.items[].major_line | object | 原始专业录取线数据对象 |
| Data.items[].major_line.SchoolName | string | 院校名称 |
| Data.items[].major_line.SchoolUUID | string | 院校唯一 ID |
| Data.items[].major_line.MajorName | string | 专业名称 |
| Data.items[].major_line.LowestScore | number | 该专业历史录取最低分 |
| Data.items[].admission_probability | number | 录取概率（0-1）；未命中可用专业预测结果时为空 |
| Data.items[].admission_probability_percent | number | 录取概率百分比 |
| Data.items[].recommendation | string | 录取概率摘要标签 |
| Data.items[].risk_label | string | 梯度标签：保、稳、冲、极大风险 |
| Data.items[].long_recommendation | string | 面向用户的原因解释 |
| Data.items[].prediction_major_name | string | 模型实际命中的专业名称 |
| Data.items[].prediction_matched | boolean | 是否匹配到可用于排序的预测结果 |
| Data.items[].prediction_error | string | 未匹配预测结果时的原因说明 |
| Data.items[].score_diff | number | 考生成绩与该专业历史最低分的差值 |
| Data.items[].prediction_evidence | object | 模型证据字段，仅 include_prediction_evidence=true 时返回 |
| Data.meta.returned_count | integer | 本页返回数量 |
| Data.meta.ranked_count | integer | 参与排序的候选数量 |
| Data.meta.candidate_limit | integer | 本次最多参与预测排序的候选数量 |
| Data.meta.line_year | integer | 专业录取线年份 |
| Data.meta.prediction_year | integer | 预测年份 |
| Data.meta.probability_sort | string | 录取概率排序方向 |
| Data.meta.prediction_group_count | integer | 本次调用录取概率预测的专业分组数量 |
| Data.meta.prediction_error_count | integer | 预测失败的专业分组数量 |
| Data.meta.prediction_skipped_count | integer | 未使用预测结果排序的专业分组数量 |
## 接口常见 HTTP 响应状态码
> 以下为接口调用中常见的 HTTP 传输层状态码，不等同于响应体内的业务状态码；完整状态码注册表以 IANA HTTP Status Code Registry 为准。
| 状态码 | 状态码解释 | 备注 |
| --- | --- | --- |
| 200 | 请求成功 | HTTP 请求已成功处理；业务状态请结合响应体中的自定义业务码判断。 |
| 201 | 资源已创建 | 创建类接口请求成功，并已生成对应资源。 |
| 202 | 请求已接受 | 请求已被接受处理，结果可能异步完成。 |
| 204 | 无响应内容 | 请求成功但响应体为空，适用于无需返回数据的操作。 |
| 400 | 请求参数错误 | 请求参数缺失、格式错误或参数组合不合法。 |
| 401 | 认证失败 | 缺少、无效或未通过认证的访问凭证（如 AppKey）。 |
| 403 | 无权限访问 | 订单到期、权限不足或接口额度不可用。 |
| 404 | 资源不存在 | 请求路径不存在。 |
| 405 | 请求方法不允许 | 当前路径不支持该 HTTP 方法。 |
| 408 | 请求超时 | 客户端请求在服务端等待时间内未完成，可稍后重试。 |
| 409 | 请求冲突 | 请求与当前资源状态冲突，调整参数或业务状态后重试。 |
| 413 | 请求内容过大 | 上传文件或请求体超过接口限制。 |
| 414 | 请求地址过长 | 请求 URL 超过服务端可处理长度，建议减少查询参数或改用 POST。 |
| 415 | 请求内容类型不支持 | 上传或请求体的内容类型不符合接口要求。 |
| 422 | 请求语义错误 | 请求格式正确，但参数取值、语义或业务约束无法处理。 |
| 429 | 请求频率受限 | 默认按来源 IP 限速，单 IP 最多 5 QPS，可满足常规业务调用。超出限制时接口会返回 429 请求频率受限；已购买接口订单可加购 10 QPS 扩展。 |
| 431 | 请求头过大 | 请求头字段过大或过多，建议精简 Header 后重试。 |
| 500 | 服务器内部错误 | 服务端处理异常，请稍后重试。 |
| 502 | 服务暂时不可用 | 请稍后重试。 |
| 503 | 服务暂时不可用 | 请稍后重试。 |
| 504 | 请求超时 | 请稍后重试。 |
## 接口自定义业务状态码
| 业务状态码 | 业务状态码解释 | 备注 |
| --- | --- | --- |
| 100 | 正常返回 | |
| 501 | 参数错误 | 缺少省份、科类、appkey，或成绩与位次均缺失，以及重复、冲突、类型或范围无效时返回；HTTP 422。 |
| 502 | 请求频率受限 | 请降低请求频率 |
| 503 | APPKEY 过期或订单失效 | 请前往开发者中心确认订单有效期 |
| 504 | APPKEY 错误 | 请检查传递的 APPKEY 是否正确 |
| 505 | 超出调用次数 | 当前 APPKEY 已达到订单调用上限 |
| -9 | 预测失败或服务处理异常 | 预测依赖失败使用 HTTP 503，超时或不可达使用 HTTP 504，内部错误使用 HTTP 500；机器状态说明具体类别。 |
## cURL 请求示例
```bash
curl --location --request POST 'https://api.gugudata.com/ai/admission/predict' \
--header 'AppKey: YOUR_APPKEY' \
--header 'Content-Type: application/json' \
--data '{"province":"江苏","subject_type":"物理类","score":635,"rank":12000,"batch":"本科批","top_n":10,"include_explanation":false,"prefer_local":false,"college_provinces":["江苏","上海"],"target_colleges":["南京大学","东南大学","南京航空航天大学","南京理工大学","苏州大学","南京邮电大学","河海大学","江南大学","上海大学","华东理工大学"],"year":2026,"local_batch_name":"本科批"}'
```
## 常见问题 Q&A
### Q: 如何完成第一次 API 调用？
A: 先确认当前接口的请求方法、必填参数和成功状态，再使用对应产品的 AppKey 发起请求；以实际响应中的业务状态判断结果。 [查看接入指南](https://www.gugudata.com/developers/getting-started)
### Q: 如何保证请求时 AppKey 的安全性？
A: 在开发者中心的 APP KEY 管理页面复制对应产品的 AppKey，并保存在服务端环境变量或密钥管理服务中。不要写入网页、App 客户端、公开仓库或日志。
### Q: 接口可以用于哪些开发语言？
A: Java、Python、Node.js、PHP、Go、C#、Swift、Kotlin 等支持 HTTP 请求的语言均可接入；也可以通过 OpenAPI、Postman 或 Apifox 查看和调试接口。
### Q: 请求失败或超时后可以重试吗？
A: 先区分 HTTP 状态与业务错误。参数、鉴权和权限错误应修正后再请求；超时并不表示服务端未执行，重试前需确认接口是否会重复计费或产生副作用。 [查看接入指南](https://www.gugudata.com/developers/errors-and-retries)
### Q: 接口的性能可以保证吗？
A: 实际响应时间受接口类型、参数和网络环境影响。请按当前套餐的 QPS 控制并发，生产接入前完成联调与容量评估。
### Q: 数据多久更新？
A: 不同接口按各自的数据周期更新，请以当前详情页的更新时间、更新频率及字段说明为准；不要将一次请求时间视为数据更新时间。
## 服务协议以及服务免责声明
- [服务协议](https://www.gugudata.com/license)
- [服务免责声明](https://www.gugudata.com/disclaimer)
## 技术支持
- 技术支持邮箱: support@gugudata.com
- 微信客服: https://work.weixin.qq.com/kfid/kfcf9a60a6afe3337b7