开发者文档

API 参考

所有鉴权端点需携带 Authorization: Bearer YOUR_API_KEY 请求头。 Base URL: /api

📊 套餐与限流

套餐价格额度QPS
免费版¥02次/天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"}'
POST/register

邮箱注册新用户

请求参数

参数名类型必填说明
emailstring邮箱地址,需符合标准邮箱格式
passwordstring密码,至少8位,需包含字母和数字

请求示例

{
  "email": "email",
  "password": "Test1234"
}

响应示例

{"email": "user@example.com", "api_key": "hc_xxxxxxxxxxxxxxxxx"}

响应字段说明

字段类型说明
emailstring注册的邮箱地址
api_keystringAPI Key,格式 hc_ + 48位hex,仅返回一次,请妥善保存
POST/auth/login

统一登录(手机号或邮箱 + 密码)

请求参数

参数名类型必填说明
accountstring手机号(11位) 或 邮箱地址
passwordstring登录密码

请求示例

{
  "account": "account",
  "password": "Test1234"
}

响应示例

{"email": "user@example.com", "api_key": "hc_xxx", "phone": "13800138000"}
POST/auth/send-code

发送手机验证码

请求参数

参数名类型必填说明
phonestring11位中国大陆手机号,格式 1[3-9]xxxxxxxxx

请求示例

{
  "phone": "phone"
}

响应示例

{"ok": true, "message": "验证码已发送"}
POST/auth/phone-login

手机验证码登录(新用户自动注册)

请求参数

参数名类型必填说明
phonestring11位手机号
codestring6位数字验证码
set_passwordstring新用户需设置密码(≥8位含字母数字),老用户留空

请求示例

{
  "phone": "phone",
  "code": "code",
  "set_password": "Test1234"
}

响应示例

{"phone": "13800138000", "api_key": "hc_xxx", "is_new": true}
POST/auth/forgot-password

申请密码重置

请求参数

参数名类型必填说明
emailstring注册邮箱

请求示例

{
  "email": "email"
}

响应示例

{"ok": true}
POST/auth/reset-password

执行密码重置

请求参数

参数名类型必填说明
tokenstring重置令牌(从邮件或服务器日志获取)
new_passwordstring新密码,≥8位含字母数字

请求示例

{
  "token": "...",
  "new_password": "new_password"
}

响应示例

{"ok": true}
GET/meBearer

当前用户信息和额度

响应示例

{"user_id": 1, "plan": "free", "used": 1, "limit": 2, "remaining": 1}
POST/detectBearer

检测单段文本中的AI幻觉

请求参数

参数名类型必填说明
textstring待检测文本,最大50,000字符,超出部分截断
strictboolean严格模式(自我一致性),每条声明多次判定后投票,更准确但约3倍耗时,默认false
domainstring领域模式: general(通用) | medical(医疗) | legal(法律) | finance(金融) | education(教育) | government(政务),默认general
knowledge_idint私有知识库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_idint本次检测ID,用于历史查询和反馈
summary.totalint提取到的声明总数
summary.redint存疑声明数(被判refuted且置信度≥0.8)
summary.yellowint疑似声明数(无法确定)
summary.greenint可信声明数(被判supported)
summary.hallucination_riskfloat幻觉风险指数 0.0~1.0
claims[].claim.textstring提取的原子声明原文
claims[].claim.typestring声明类型: factual(事实) | logical(逻辑) | subjective(主观) | common(常识)
claims[].verification.statusstring判定结果: supported(支持) | refuted(反驳) | unverified(无法核实)
claims[].verification.confidencefloat置信度 0.0~1.0
claims[].verification.sourcesarray搜索来源列表 [{title, url, snippet}]
claims[].correction.correctedstring修正建议文本(仅refuted时有)
POST/detect-streamBearer

SSE 流式检测(逐声明实时推送)

请求参数

参数名类型必填说明
textstring待检测文本
strictboolean严格模式,默认false
domainstring领域模式

请求示例

{
  "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,...}
POST/batchBearer

批量检测整篇文档(按段拆分)+ 可选自动重写

请求参数

参数名类型必填说明
textstring待检测的完整文档
auto_rewriteboolean是否自动修正未通过段落并重检,默认false
max_iterationsint最大重写轮数(含首轮),1~5,默认3
strictboolean严格模式
domainstring领域模式

请求示例

{
  "text": "text",
  "auto_rewrite": false,
  "max_iterations": 1,
  "strict": false,
  "domain": "domain"
}

响应示例

{"report":{"overall":{"segments":5,"resolved":4,"unresolved":1},"segments":[...]}}
POST/source-checkBearer

源文档对照:检测AI摘要是否忠于源文档

请求参数

参数名类型必填说明
sourcestring源文档原文,最大50,000字符
summarystringAI生成的摘要文本,最大20,000字符
domainstring领域模式

请求示例

{
  "source": "source",
  "summary": "summary",
  "domain": "domain"
}

响应示例

{"report":{"summary":{"total":5,"red":0,"yellow":1,"green":4,"faithfulness":0.8},"claims":[...]}}
POST/billing/ordersBearer

创建支付订单

请求参数

参数名类型必填说明
planstring套餐: pro(¥49/月,500次) | pro99(¥99/月,2000次) | api(¥0.1/次)
providerstring支付方式: wxpay | alipay
periodstring周期: month(默认) | year(年付=10个月)

请求示例

{
  "plan": "plan",
  "provider": "provider",
  "period": "period"
}

响应示例

{"order_id":1,"plan":"pro","amount":4900,"provider":"wxpay","status":"pending","qr_code":"...","pay_url":"..."}
GET/billing/subscriptionBearer

当前订阅状态

响应示例

{"subscribed":true,"plan":"pro","status":"active","current_period_end":"2026-08-22"}
GET/historyBearer

最近检测列表

请求参数

参数名类型必填说明
limitint返回条数,默认20

响应示例

{"items":[{"id":1,"input":"...","llm_calls":3,"search_calls":1,"created_at":"2026-07-27"}]}
GET/history/{id}Bearer

某次检测的完整结果

响应示例

{"id":1,"input":"...","result":{"summary":{...},"claims":[...]}}
GET/detect/{id}/exportBearer

导出检测结果JSON

请求参数

参数名类型必填说明
fmtstring格式,默认json

响应示例

导出文件: hallucc-result-{id}.json
POST/feedbackBearer

对声明标记准/不准

请求参数

参数名类型必填说明
detection_idint检测ID
claim_idint声明ID
labelstringup(准) | down(不准)

请求示例

{
  "detection_id": 1,
  "claim_id": 1,
  "label": "label"
}

响应示例

{"ok": true}
POST/guard/checkBearer

AI安全检测:Prompt注入/越狱/有害内容 + 可选幻觉检测

请求参数

参数名类型必填说明
promptstring用户原始输入(用于注入检测)
outputstringAI的响应文本
check_hallucinationboolean是否同时运行幻觉检测,默认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":"加固系统提示词..."}]}
POST/detect-agentBearer

Agent输出检测:最终回答 + 可选中间步骤六维结构化评估

请求参数

参数名类型必填说明
agent_outputstringAgent的最终回答文本,最大50,000字符
stepsarray中间步骤列表 [{step, thought, action, action_input, observation, final_answer}]
domainstring领域模式: general|medical|legal|finance|education|government,默认general
speedstring速度: fast(纯规则,0 LLM)|standard(默认)|deep(多模型投票)
tool_schemasobject工具 JSON Schema(用于 HALLUCINATED_TOOL/SCHEMA_VIOLATION 判定),留空则跳过
taskstring原始任务指令(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}}

响应字段说明

字段类型说明
mainobject最终回答的文本级检测结果 {input, summary, claims}
steps[].checksarray逐步检查项 [{type, verdict, detail, source, confidence}](claims 恒为空,真实数据在 checks)
dimensionsobject顶层六维评估(fast 档 LLM 维度 confidence=0.0)
failure_modesarray[{code, step, severity, detail, confidence, check_type}]
POST/detect-agent-trajectoryBearer

Agent全链路轨迹检测:分层管线六维评估+幻觉传播DAG

请求参数

参数名类型必填说明
trajectoryarray执行轨迹(1~20步) [{step, thought, action, action_input, observation, final_answer}]
domainstring领域模式: general|medical|legal|finance|education|government
speedstring速度: fast|standard(默认)|deep
tool_schemasobject工具 JSON Schema
taskstring原始任务指令(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.dimensionsobject六维评估(嵌套在 summary 下,区别于 /detect-agent 的顶层 dimensions);fast 档 LLM 维度 confidence=0.0
summary.llm_calls/search_calls/truncatedint/bool成本与截断标记(超 MAX_TRAJECTORY_LLM_CALLS 截断裁判层)
steps[].checksarray逐步检查项 [{type, verdict, detail, source, confidence}](claims 恒为空)
propagation[].to_stepsarray传播目标为 int 数组(v2,非 v1 单数 to_step)
failure_modesarray[{code, step, severity, detail, confidence, check_type}]
POST/knowledgeBearer

创建私有知识库(可选同时上传首份文档)

请求参数

参数名类型必填说明
namestring知识库名称,1~100 字(multipart Form 字段,非 JSON)
filefile首份文档(multipart 文件字段,支持 txt/md/docx/pdf,可选)

请求示例

{
  "name": "name",
  "file": ""
}

响应示例

{"kb_id": 1, "name": "产品知识库", "chunk_count": 0}

响应字段说明

字段类型说明
kb_idint新建知识库 ID
namestring知识库名称
chunk_countint分段数;创建时未上传文件为 0,上传了则为该文档分段数
GET/knowledgeBearer

列出当前用户的知识库

响应示例

{"items":[{"kb_id":1,"name":"产品知识库","filename":"spec.pdf","status":"ready","chunk_count":42,"created_at":"2026-08-30"}]}

响应字段说明

字段类型说明
items[].kb_idint知识库 ID
items[].namestring知识库名称
items[].filenamestring已上传文档文件名(未上传为空字符串)
items[].statusstring状态: empty(未上传文档) | ready(已上传并分段)
items[].chunk_countint文档分段数
items[].created_atstring创建日期
DELETE/knowledge/{kb_id}Bearer

删除知识库及其全部分段

请求参数

参数名类型必填说明
kb_idint路径参数:知识库 ID

响应示例

{"ok": true}
POST/knowledge/{kb_id}/uploadBearer

向已有知识库上传文档(提取文本并分段)

请求参数

参数名类型必填说明
kb_idint路径参数:知识库 ID
filefilemultipart 文件字段,支持 txt/md/docx/pdf

请求示例

{
  "kb_id": 1,
  "file": ""
}

响应示例

{"kb_id": 1, "filename": "spec.pdf", "chunk_count": 42}

响应字段说明

字段类型说明
kb_idint知识库 ID
filenamestring已上传文档文件名
chunk_countint本次提取的文档分段数
GET/health

健康检查

响应示例

{"status":"ok","search_backend":"qianfan","llm_provider":"deepseek","redis":"connected"}
GET/models

可用LLM模型列表

响应示例

{"active":"deepseek","providers":[{"name":"deepseek","default_model":"deepseek-chat","active":true},...]}
GET/domains

可用领域模式(6 个领域均 available,is_default 标记当前默认)

响应示例

{"default":"general","domains":[{"key":"general","name":"通用","available":true,"is_default":true},{"key":"medical","name":"医疗","available":true,"is_default":false},...]}

响应字段说明

字段类型说明
defaultstring当前默认领域 key(config.domain,可用 /detect?domain= 按请求覆盖)
domains[].availableboolean该领域是否已就绪可检测(恒为 true,6 个领域全部可用)
domains[].is_defaultboolean是否当前默认领域(仅表示「默认」而非「是否可用」,只有 default 那个为 true)