API 参考
所有鉴权端点需携带 Authorization: Bearer YOUR_API_KEY 请求头。 Base URL: /api
📊 套餐与限流
| 套餐 | 价格 | 额度 | QPS |
|---|---|---|---|
| 免费版 | ¥0 | 2次/天 | 2 |
| Pro版 | ¥49/月 | 500次/月 | 10 |
| Pro增强版 | ¥99/月 | 2000次/月 | 20 |
| API版 | ¥0.1/次 | 按量计费 | 20 |
快速开始
# 1. 注册获取 API Key
curl -X POST /api/register \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"YourPass123"}'
# 2. 调用检测(替换 YOUR_API_KEY)
curl -X POST /api/detect \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"DeepSeek由字节跳动开发","strict":false,"domain":"general"}'/register邮箱注册新用户
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | ● | 邮箱地址,需符合标准邮箱格式 | |
| password | string | ● | 密码,至少8位,需包含字母和数字 |
请求示例
{
"email": "email",
"password": "Test1234"
}响应示例
{"email": "user@example.com", "api_key": "hc_xxxxxxxxxxxxxxxxx"}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| string | 注册的邮箱地址 | |
| api_key | string | API Key,格式 hc_ + 48位hex,仅返回一次,请妥善保存 |
/auth/login统一登录(手机号或邮箱 + 密码)
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| account | string | ● | 手机号(11位) 或 邮箱地址 |
| password | string | ● | 登录密码 |
请求示例
{
"account": "account",
"password": "Test1234"
}响应示例
{"email": "user@example.com", "api_key": "hc_xxx", "phone": "13800138000"}/auth/send-code发送手机验证码
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | string | ● | 11位中国大陆手机号,格式 1[3-9]xxxxxxxxx |
请求示例
{
"phone": "phone"
}响应示例
{"ok": true, "message": "验证码已发送"}/auth/phone-login手机验证码登录(新用户自动注册)
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | string | ● | 11位手机号 |
| code | string | ● | 6位数字验证码 |
| set_password | string | ○ | 新用户需设置密码(≥8位含字母数字),老用户留空 |
请求示例
{
"phone": "phone",
"code": "code",
"set_password": "Test1234"
}响应示例
{"phone": "13800138000", "api_key": "hc_xxx", "is_new": true}/auth/forgot-password申请密码重置
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | ● | 注册邮箱 |
请求示例
{
"email": "email"
}响应示例
{"ok": true}/auth/reset-password执行密码重置
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| token | string | ● | 重置令牌(从邮件或服务器日志获取) |
| new_password | string | ● | 新密码,≥8位含字母数字 |
请求示例
{
"token": "...",
"new_password": "new_password"
}响应示例
{"ok": true}/meBearer当前用户信息和额度
响应示例
{"user_id": 1, "plan": "free", "used": 1, "limit": 2, "remaining": 1}/detectBearer检测单段文本中的AI幻觉
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | ● | 待检测文本,最大50,000字符,超出部分截断 |
| strict | boolean | ○ | 严格模式(自我一致性),每条声明多次判定后投票,更准确但约3倍耗时,默认false |
| domain | string | ○ | 领域模式: general(通用) | medical(医疗) | legal(法律) | finance(金融) | education(教育) | government(政务),默认general |
| knowledge_id | int | ○ | 私有知识库ID,传入后验证时优先比对知识库内容(企业版,需先 POST /knowledge 上传文档) |
请求示例
{
"text": "text",
"strict": false,
"domain": "domain",
"knowledge_id": 1
}响应示例
{"detection_id":1, "input":"…", "summary":{"total":3,"red":1,"yellow":1,"green":1,"hallucination_risk":0.67}, "claims":[...], "quota":{"remaining":1}, "strict":false, "domain":"general"}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| detection_id | int | 本次检测ID,用于历史查询和反馈 |
| summary.total | int | 提取到的声明总数 |
| summary.red | int | 存疑声明数(被判refuted且置信度≥0.8) |
| summary.yellow | int | 疑似声明数(无法确定) |
| summary.green | int | 可信声明数(被判supported) |
| summary.hallucination_risk | float | 幻觉风险指数 0.0~1.0 |
| claims[].claim.text | string | 提取的原子声明原文 |
| claims[].claim.type | string | 声明类型: factual(事实) | logical(逻辑) | subjective(主观) | common(常识) |
| claims[].verification.status | string | 判定结果: supported(支持) | refuted(反驳) | unverified(无法核实) |
| claims[].verification.confidence | float | 置信度 0.0~1.0 |
| claims[].verification.sources | array | 搜索来源列表 [{title, url, snippet}] |
| claims[].correction.corrected | string | 修正建议文本(仅refuted时有) |
/detect-streamBearerSSE 流式检测(逐声明实时推送)
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | ● | 待检测文本 |
| strict | boolean | ○ | 严格模式,默认false |
| domain | string | ○ | 领域模式 |
请求示例
{
"text": "text",
"strict": false,
"domain": "domain"
}响应示例
event: claim
data: {"claim_id":1,"text":"...","status":"refuted","confidence":0.92}
event: summary
data: {"total":3,"red":1,...}/batchBearer批量检测整篇文档(按段拆分)+ 可选自动重写
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | ● | 待检测的完整文档 |
| auto_rewrite | boolean | ○ | 是否自动修正未通过段落并重检,默认false |
| max_iterations | int | ○ | 最大重写轮数(含首轮),1~5,默认3 |
| strict | boolean | ○ | 严格模式 |
| domain | string | ○ | 领域模式 |
请求示例
{
"text": "text",
"auto_rewrite": false,
"max_iterations": 1,
"strict": false,
"domain": "domain"
}响应示例
{"report":{"overall":{"segments":5,"resolved":4,"unresolved":1},"segments":[...]}}/source-checkBearer源文档对照:检测AI摘要是否忠于源文档
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| source | string | ● | 源文档原文,最大50,000字符 |
| summary | string | ● | AI生成的摘要文本,最大20,000字符 |
| domain | string | ○ | 领域模式 |
请求示例
{
"source": "source",
"summary": "summary",
"domain": "domain"
}响应示例
{"report":{"summary":{"total":5,"red":0,"yellow":1,"green":4,"faithfulness":0.8},"claims":[...]}}/billing/ordersBearer创建支付订单
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| plan | string | ● | 套餐: pro(¥49/月,500次) | pro99(¥99/月,2000次) | api(¥0.1/次) |
| provider | string | ● | 支付方式: wxpay | alipay |
| period | string | ○ | 周期: month(默认) | year(年付=10个月) |
请求示例
{
"plan": "plan",
"provider": "provider",
"period": "period"
}响应示例
{"order_id":1,"plan":"pro","amount":4900,"provider":"wxpay","status":"pending","qr_code":"...","pay_url":"..."}/billing/subscriptionBearer当前订阅状态
响应示例
{"subscribed":true,"plan":"pro","status":"active","current_period_end":"2026-08-22"}/historyBearer最近检测列表
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit | int | ○ | 返回条数,默认20 |
响应示例
{"items":[{"id":1,"input":"...","llm_calls":3,"search_calls":1,"created_at":"2026-07-27"}]}/history/{id}Bearer某次检测的完整结果
响应示例
{"id":1,"input":"...","result":{"summary":{...},"claims":[...]}}/detect/{id}/exportBearer导出检测结果JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fmt | string | ○ | 格式,默认json |
响应示例
导出文件: hallucc-result-{id}.json/feedbackBearer对声明标记准/不准
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| detection_id | int | ● | 检测ID |
| claim_id | int | ● | 声明ID |
| label | string | ● | up(准) | down(不准) |
请求示例
{
"detection_id": 1,
"claim_id": 1,
"label": "label"
}响应示例
{"ok": true}/guard/checkBearerAI安全检测:Prompt注入/越狱/有害内容 + 可选幻觉检测
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt | string | ○ | 用户原始输入(用于注入检测) |
| output | string | ● | AI的响应文本 |
| check_hallucination | boolean | ○ | 是否同时运行幻觉检测,默认false |
请求示例
{
"prompt": "prompt",
"output": "output",
"check_hallucination": false
}响应示例
{"passed":false,"risk_score":0.95,"risk_level":"critical","summary":"检测到有害内容(3项威胁),建议立即拦截","threats":[{"category":"LLM01-DI","category_name":"直接注入","severity":0.95,"match_context":"...","recommendation":"加固系统提示词..."}]}/detect-agentBearerAgent输出检测:最终回答 + 可选中间步骤六维结构化评估
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| agent_output | string | ● | Agent的最终回答文本,最大50,000字符 |
| steps | array | ○ | 中间步骤列表 [{step, thought, action, action_input, observation, final_answer}] |
| domain | string | ○ | 领域模式: general|medical|legal|finance|education|government,默认general |
| speed | string | ○ | 速度: fast(纯规则,0 LLM)|standard(默认)|deep(多模型投票) |
| tool_schemas | object | ○ | 工具 JSON Schema(用于 HALLUCINATED_TOOL/SCHEMA_VIOLATION 判定),留空则跳过 |
| task | string | ○ | 原始任务指令(task_completion 裁判用) |
请求示例
{
"agent_output": "agent_output",
"steps": "",
"domain": "domain",
"speed": "speed",
"tool_schemas": "",
"task": "task"
}响应示例
{"detection_id":1,"main":{"summary":{...},"claims":[...]},"steps":[{"step":1,"tool":"search","claim":"...","tool_claim_mismatch":false,"checks":[{"type":"tool_existence","verdict":"pass","detail":"...","source":"deterministic","confidence":1.0}]}],"dimensions":{"tool_selection":{"score":0.9,"confidence":1.0},"parameter_validity":{"score":0.8,"confidence":1.0},"observation_faithfulness":{"score":0.7,"confidence":0.85},"reasoning_coherence":{"score":0.9,"confidence":0.8},"task_completion":{"score":0.9,"confidence":0.0},"trajectory_efficiency":{"score":1.0,"confidence":1.0}},"failure_modes":[{"code":"CLAIM_MISMATCH","step":2,"severity":"medium","detail":"观察与声称不一致","confidence":0.85,"check_type":"llm_judge"}],"quota":{"used":1,"limit":500,"remaining":499}}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| main | object | 最终回答的文本级检测结果 {input, summary, claims} |
| steps[].checks | array | 逐步检查项 [{type, verdict, detail, source, confidence}](claims 恒为空,真实数据在 checks) |
| dimensions | object | 顶层六维评估(fast 档 LLM 维度 confidence=0.0) |
| failure_modes | array | [{code, step, severity, detail, confidence, check_type}] |
/detect-agent-trajectoryBearerAgent全链路轨迹检测:分层管线六维评估+幻觉传播DAG
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| trajectory | array | ● | 执行轨迹(1~20步) [{step, thought, action, action_input, observation, final_answer}] |
| domain | string | ○ | 领域模式: general|medical|legal|finance|education|government |
| speed | string | ○ | 速度: fast|standard(默认)|deep |
| tool_schemas | object | ○ | 工具 JSON Schema |
| task | string | ○ | 原始任务指令(task_completion 裁判用) |
请求示例
{
"trajectory": "",
"domain": "domain",
"speed": "speed",
"tool_schemas": "",
"task": "task"
}响应示例
{"detection_id":1,"summary":{"total_steps":3,"hallucinated_steps":2,"clean_steps":1,"propagation_chains":1,"llm_calls":2,"search_calls":1,"truncated":false,"dimensions":{"tool_selection":{"score":0.9,"confidence":1.0},"parameter_validity":{"score":0.8,"confidence":1.0},"observation_faithfulness":{"score":0.7,"confidence":0.85},"reasoning_coherence":{"score":0.9,"confidence":0.8},"task_completion":{"score":0.9,"confidence":0.8},"trajectory_efficiency":{"score":1.0,"confidence":1.0}}},"steps":[{"step":1,"action":"search","has_hallucination":false,"claims":[],"checks":[{"type":"tool_existence","verdict":"pass","detail":"...","source":"deterministic","confidence":1.0}]}],"propagation":[{"from_step":2,"to_steps":[3,4],"claim":"...","confidence":0.9}],"failure_modes":[{"code":"CLAIM_MISMATCH","step":2,"severity":"medium","detail":"...","confidence":0.85,"check_type":"llm_judge"}],"quota":{"used":1,"limit":500,"remaining":499}}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| summary.dimensions | object | 六维评估(嵌套在 summary 下,区别于 /detect-agent 的顶层 dimensions);fast 档 LLM 维度 confidence=0.0 |
| summary.llm_calls/search_calls/truncated | int/bool | 成本与截断标记(超 MAX_TRAJECTORY_LLM_CALLS 截断裁判层) |
| steps[].checks | array | 逐步检查项 [{type, verdict, detail, source, confidence}](claims 恒为空) |
| propagation[].to_steps | array | 传播目标为 int 数组(v2,非 v1 单数 to_step) |
| failure_modes | array | [{code, step, severity, detail, confidence, check_type}] |
/knowledgeBearer创建私有知识库(可选同时上传首份文档)
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | ● | 知识库名称,1~100 字(multipart Form 字段,非 JSON) |
| file | file | ○ | 首份文档(multipart 文件字段,支持 txt/md/docx/pdf,可选) |
请求示例
{
"name": "name",
"file": ""
}响应示例
{"kb_id": 1, "name": "产品知识库", "chunk_count": 0}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| kb_id | int | 新建知识库 ID |
| name | string | 知识库名称 |
| chunk_count | int | 分段数;创建时未上传文件为 0,上传了则为该文档分段数 |
/knowledgeBearer列出当前用户的知识库
响应示例
{"items":[{"kb_id":1,"name":"产品知识库","filename":"spec.pdf","status":"ready","chunk_count":42,"created_at":"2026-08-30"}]}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| items[].kb_id | int | 知识库 ID |
| items[].name | string | 知识库名称 |
| items[].filename | string | 已上传文档文件名(未上传为空字符串) |
| items[].status | string | 状态: empty(未上传文档) | ready(已上传并分段) |
| items[].chunk_count | int | 文档分段数 |
| items[].created_at | string | 创建日期 |
/knowledge/{kb_id}Bearer删除知识库及其全部分段
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kb_id | int | ● | 路径参数:知识库 ID |
响应示例
{"ok": true}/knowledge/{kb_id}/uploadBearer向已有知识库上传文档(提取文本并分段)
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kb_id | int | ● | 路径参数:知识库 ID |
| file | file | ● | multipart 文件字段,支持 txt/md/docx/pdf |
请求示例
{
"kb_id": 1,
"file": ""
}响应示例
{"kb_id": 1, "filename": "spec.pdf", "chunk_count": 42}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| kb_id | int | 知识库 ID |
| filename | string | 已上传文档文件名 |
| chunk_count | int | 本次提取的文档分段数 |
/health健康检查
响应示例
{"status":"ok","search_backend":"qianfan","llm_provider":"deepseek","redis":"connected"}/models可用LLM模型列表
响应示例
{"active":"deepseek","providers":[{"name":"deepseek","default_model":"deepseek-chat","active":true},...]}/domains可用领域模式(6 个领域均 available,is_default 标记当前默认)
响应示例
{"default":"general","domains":[{"key":"general","name":"通用","available":true,"is_default":true},{"key":"medical","name":"医疗","available":true,"is_default":false},...]}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| default | string | 当前默认领域 key(config.domain,可用 /detect?domain= 按请求覆盖) |
| domains[].available | boolean | 该领域是否已就绪可检测(恒为 true,6 个领域全部可用) |
| domains[].is_default | boolean | 是否当前默认领域(仅表示「默认」而非「是否可用」,只有 default 那个为 true) |