题库API对接文档

版本：v1.2 更新时间：2026-04-23 接口地址：https://so.ucuc.net/prod-api/system/questionBank/search

一、题目搜索接口

接口信息

项目说明请求地址https://so.ucuc.net/prod-api/system/questionBank/search请求方式POSTContent-Typeapplication/json 搜索流程

检查内存缓存（命中则直接返回，不扣次数）
调用上游远程API，携带题目内容（q）、题型（type，可选）、选项（options，可选）
若上游API未找到答案，降级查询本地数据库（全文检索 + 关键词匹配）
返回结果，扣除用户次数

二、请求参数说明

请求体为 JSON 格式。

参数名类型必填说明questionString✅ 是题目内容（完整题目文本）apiKeyString✅ 是用户专属 API Key，在个人中心获取typeString否题型，如单选题、多选题等。不传则自动检测，传入可提升准确率optionsString否题目选项 JSON 数组字符串，如 ["A.选项1","B.选项2"]，传入后可进一步提升准确度请求示例

最简请求（仅传题目 + apiKey）：

{
  "question": "下列关于细胞的说法，正确的是？",
  "apiKey": "your_api_key"
}

完整请求（携带题型和选项）：

{
  "question": "下列关于细胞的说法，正确的是？",
  "apiKey": "your_api_key",
  "type": "单选题",
  "options": "["A.细胞是生命活动的基本单位","B.所有细胞都有细胞壁","C.所有细胞都有线粒体","D.原核细胞没有以膜为基础的细胞器"]"
}

化学类题目示例：

{
  "question": "Ca2+通道开放后，Ca2+内流，引起肌肉收缩，该过程的离子转运方式是？",
  "apiKey": "your_api_key",
  "type": "单选题"
}

三、响应结构说明

外层通用结构

{
  "code": 200,
  "msg": "查询成功",
  "data": { ... }
}

字段类型说明codeInteger状态码，200 表示成功msgString操作消息dataObject响应数据，见下表 data 字段说明

字段类型说明titleString题目内容（与请求的 question 一致）answerString答案。未找到时为 null 或空typeString题目类型，如单选题、多选题等kcnameString课程名称（本地数据库来源时有值）sourceString答案来源：remote（远程）/ local（本地）/ cache（缓存）scoreDouble本地数据库匹配分数（仅本地来源有值）remainingCountInteger搜索后用户剩余次数（已扣除本次）响应示例

找到答案（远程API）：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "title": "下列关于细胞的说法，正确的是？",
    "answer": "A",
    "type": "单选题",
    "kcname": null,
    "source": "remote",
    "score": null,
    "remainingCount": 99
  }
}

找到答案（本地数据库）：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "title": "下列关于细胞的说法，正确的是？",
    "answer": "A.细胞是生命活动的基本单位",
    "type": "单选题",
    "kcname": "生物学",
    "source": "local",
    "score": 18.5,
    "remainingCount": 98
  }
}

未找到答案：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "title": "下列关于细胞的说法，正确的是？",
    "answer": null,
    "type": null,
    "source": null,
    "remainingCount": 97
  }
}

余额不足：

{
  "code": 500,
  "msg": "余额不足，请充值后再使用"
}

四、题型枚举

传入值说明单选题单项选择题多选题多项选择题判断题判断正误题填空题填写空白题简答题简述回答题不传 / null由系统和上游API自动识别题型 💡 传入正确题型可显著提升搜索准确度，尤其是单选题与多选题的区分。

五、错误码说明

code说明200成功（包括未找到答案，但请求本身成功）500服务端异常，如余额不足、apiKey 无效等，详见 msg 六、完整示例

JavaScript / Axios 示例

import axios from "axios"

async function searchQuestion(apiKey, question, type = null, options = null) {
  const params = {
    question: question.trim(),
    apiKey: apiKey,
    type: (type && type !== "自动检测") ? type : null,
    options: options && options.length > 0 ? JSON.stringify(options) : null
  }

  const response = await axios.post(
    "https://so.ucuc.net/prod-api/system/questionBank/search",
    params,
    { headers: { "Content-Type": "application/json" } }
  )

  if (response.data.code === 200) {
    const result = response.data.data
    console.log("答案：", result.answer)
    console.log("题型：", result.type)
    console.log("来源：", result.source)
    console.log("剩余次数：", result.remainingCount)
    return result
  } else {
    throw new Error(response.data.msg)
  }
}

// 调用示例
searchQuestion("your_api_key", "下列关于细胞的说法，正确的是？", "单选题", [
  "A.细胞是生命活动的基本单位",
  "B.所有细胞都有细胞壁"
])

Python / requests 示例

import requests
import json

def search_question(api_key, question, q_type=None, options=None):
    payload = {
        "question": question.strip(),
        "apiKey": api_key,
        "type": q_type if q_type and q_type != "自动检测" else None,
        "options": json.dumps(options, ensure_ascii=False) if options else None
    }

    resp = requests.post(
        "https://so.ucuc.net/prod-api/system/questionBank/search",
        json=payload,
        headers={"Content-Type": "application/json"},
        timeout=15
    )

    data = resp.json()
    if data["code"] == 200:
        result = data["data"]
        print(f"答案: {result.get("answer")}")
        print(f"题型: {result.get("type")}")
        print(f"来源: {result.get("source")}")
        print(f"剩余次数: {result.get("remainingCount")}")
        return result
    else:
        raise Exception(data["msg"])

# 调用示例
search_question(
    api_key="your_api_key",
    question="Ca2+通道开放后，Ca2+内流，引起肌肉收缩，该过程的离子转运方式是？",
    q_type="单选题"
)

cURL 示例

curl -X POST "https://so.ucuc.net/prod-api/system/questionBank/search" 
  -H "Content-Type: application/json" 
  -d "{
    "question": "下列关于细胞的说法，正确的是？",
    "apiKey": "your_api_key",
    "type": "单选题",
    "options": "[\"A.细胞是生命活动的基本单位\",\"B.所有细胞都有细胞壁\"]"
  }"

七、注意事项

apiKey 获取：登录后在个人中心可查看专属 API Key，请妥善保管，勿泄露。
次数扣减：每次成功搜索（命中缓存之外）都会扣减用户次数。短时间内重复查询相同题目命中内存缓存时不扣次数。
题型传入建议：单选/多选题建议传入 type 参数以提高准确率；化学、物理类题目建议同时传入 options；简答题/填空题不传 type 亦可正常工作。
超时设置：建议调用方设置不少于 15 秒的请求超时。
字符编码：请求体使用 UTF-8 编码，题目内容无需自行 URL 编码（由后端处理）。