API 对接文档

供第三方开发者集成 AI 搜题能力。基础路径：https://你的域名/api

1. 基本信息

协议	HTTPS（生产环境建议）
格式	`application/json; charset=utf-8`
编码	UTF-8

统一响应

成功时返回 code、message、data；失败时无 data。

{
  "code": 200,
  "message": "success",
  "data": { }
}

HTTP	code	说明
200	200	成功
400	400	参数错误
401	401	未认证
403	403	无权限
429	429	次数不足
500	500	服务器错误

2. 认证方式

对接搜题推荐使用 API Key（用户中心 → API 密钥，32 位十六进制字符串）。

方式	示例
请求头（推荐）	`X-Api-Key: 你的密钥`
备用请求头	`X-User-Key: 你的密钥`
查询参数	`?api_key=你的密钥`
JSON 体	`{"api_key":"你的密钥", ...}`
Web 登录	`Authorization: Bearer <64位Token>`

同时提供 Key 与 Token 时，API Key 优先。

3. 快速开始

健康检查

GET/api/health

无需认证，用于检测服务是否可用。

单选题搜题

POST/api/ask

curl -X POST "https://你的域名/api/ask" \
  -H "X-Api-Key: 你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "0",
    "question": "下列哪项是 PHP 的文件扩展名？",
    "options": [".php", ".java", ".py", ".go"],
    "provider": "deepseek"
  }'

{
  "code": 200,
  "message": "success",
  "data": {
    "valid": true,
    "answer": ["A"],
    "provider": "deepseek",
    "provider_name": "DeepSeek",
    "model": "deepseek-chat",
    "duration_ms": 1234
  }
}

AI 调用成功即扣 1 次额度，即使 valid 为 false（答案解析失败）。

4. 搜题接口

POST/api/ask

字段	类型	必填	说明
type	string	否	题型，默认 `0`
question	string	是	题目正文
options	array	否	选项（字符串数组，不含 A/B 前缀）
blank_count	int	否	填空题空数，别名 blankCount
provider	string	否	AI 接口 ID，默认系统配置
model	string	否	模型名称
temperature	float	否	采样温度
max_tokens	int	否	最大输出 token

5. 题型与答案格式

type	题型	answer 示例
0	单选题	`["A"]`
1	多选题	`["A","C"]`
2	填空题	`["答案1","答案2"]`
3	判断题	`["true"]` 或 `["false"]`
4	简答题	`["参考答案"]`
5	名词解释	`["解释内容"]`
6	论述题	`["论述内容"]`
7	计算题	`["计算过程"]`
15	阅读理解	子题数组

填空题示例

{
  "type": "2",
  "question": "中国的首都是____，最大城市之一是____。",
  "blank_count": 2
}

6. 代码示例

Python

import requests

resp = requests.post(
    "https://你的域名/api/ask",
    headers={"X-Api-Key": "你的密钥"},
    json={
        "type": "0",
        "question": "1+1=?",
        "options": ["1", "2", "3", "4"],
        "provider": "deepseek",
    },
    timeout=60,
)
data = resp.json()
if data["code"] != 200:
    raise RuntimeError(data["message"])
print(data["data"]["answer"])

JavaScript

const resp = await fetch('https://你的域名/api/ask', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': '你的密钥',
  },
  body: JSON.stringify({
    type: '0',
    question: '1+1=?',
    options: ['1', '2', '3', '4'],
  }),
});
const json = await resp.json();
if (json.code !== 200) throw new Error(json.message);
console.log(json.data.answer);

PHP

$ch = curl_init('https://你的域名/api/ask');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: 你的密钥',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => '0',
        'question' => '1+1=?',
        'options' => ['1', '2', '3', '4'],
    ], JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 60,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

7. 额度与套餐

扣费优先级：生效套餐 → 今日免费次数 → 账户余额。

GET/api/auth/me

返回 user（含 quota_used、daily_quota、balance）及 subscription（当前套餐，无则为 null）。

接口	说明
GET /api/user/plans	可购套餐（无需登录）
GET /api/user/subscription	当前套餐状态
POST /api/user/plans/{id}/purchase	购买套餐
GET /api/user/orders	我的订单

8. 用户接口一览

方法	路径	认证	说明
POST	/api/auth/register	否	注册
POST	/api/auth/login	否	登录，返回 token 与 api_key
POST	/api/auth/logout	Token	退出
GET	/api/auth/me	Key/Token	当前用户
GET	/api/user/key	Token	查看 API Key
POST	/api/user/key/reset	Token	重置 API Key
GET	/api/user/logs	Key/Token	搜题日志（支持 keyword、status、date_from 等筛选）
GET	/api/providers	否	AI 接口列表

登录示例

POST /api/auth/login
{
  "username": "demo_user",
  "password": "123456"
}

9. AI 接口

GET/api/providers

常用 provider ID：

provider	名称
deepseek	DeepSeek
qwen-dashscope	通义千问
zhipu-glm	智谱 GLM
kimi	Kimi
openai	OpenAI
anthropic	Anthropic

10. 错误处理

401：检查 API Key 是否正确、用户是否被封禁
429：次数不足或套餐 IP 超限，引导购买套餐
400：检查 question、options 等参数
500：AI 服务异常，可有限重试（建议指数退避）

11. 注意事项

API Key 仅用于服务端，切勿暴露在前端或客户端
建议 HTTP 超时 ≥ 60 秒
429 不应自动重试；500 可有限重试
部分套餐限制绑定 IP 数量
完整 Markdown 文档见项目 docs/API.md