快速入门
3 步完成你的第一次 API 调用
2
创建密钥
进入「API密钥」页面,点击创建,获得 hk_xxx 密钥
3
发起调用
在请求 Header 中携带 X-API-Key,即可调用所有接口
第一次调用 · curl
curl -X GET "https://api.cnhk.net/api/v1/search?q=PHP%E5%AE%89%E5%85%A8&limit=3" \ -H "X-API-Key: hk_your_api_key_here"
认证方式
所有 API 请求(除 /api/health 外)都需要在 Header 中携带 API 密钥:
X-API-Key: hk_your_api_key_here
也可以通过 URL 参数传递(不推荐,密钥会暴露在日志中):
GET /api/v1/search?q=关键词&api_key=hk_your_key
安全提示:API 密钥等同于密码,请勿在客户端代码(浏览器/APP)中硬编码。建议通过后端代理调用,或使用环境变量管理。
限流与配额
| 套餐 | QPS 限流 | 日配额 | 月配额 | AI 问答 |
|---|---|---|---|---|
| 免费版 | 10/分钟 | 100 次 | 3,000 次 | 有限 |
| 基础版 | 60/分钟 | 1,000 次 | 30,000 次 | 标准 |
| 专业版 | 300/分钟 | 10,000 次 | 300,000 次 | 高级 |
| 企业版 | 定制 | 定制 | 定制 | 无限制 |
超出限流会返回 429 Too Many Requests。可通过 /api/v1/usage 接口实时查询当前配额使用情况。
错误码
| HTTP 状态码 | 含义 | 处理建议 |
|---|---|---|
200 | 请求成功 | 正常处理返回数据 |
400 | 参数错误 | 检查必填参数是否缺失或格式不正确 |
401 | 未认证 | API 密钥缺失或无效,检查 X-API-Key Header |
403 | 无权限 | 密钥已禁用或当前套餐不支持该接口 |
404 | 资源不存在 | 请求的文档 ID 或接口路径不存在 |
429 | 请求过于频繁 | 触发限流,降低请求频率或升级套餐 |
500 | 服务器内部错误 | 服务端异常,请稍后重试或联系技术支持 |
错误响应统一格式:
{
"error": "错误描述",
"code": 400
}
接口列表
GET
/api/v1/search
知识库语义检索
基于向量检索 + 重排序的知识库搜索,返回最相关的文档片段
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
q |
string | 必填 | 搜索关键词 |
limit |
int | 可选 | 返回数量,默认5,最大20 |
调用示例
curl -X GET "https://api.cnhk.net/api/v1/search?q=示例值" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"query": "关键词",
"total": 5,
"results": [
{
"document_id": 1,
"title": "文档标题",
"content": "内容摘要...",
"similarity": 0.92,
"rerank_score": 0.88,
"url": "https:\/\/zsd.cnhk.net\/article\/1"
}
]
}
GET
/api/v1/documents
获取文档列表
分页获取已发布的文档列表,支持按分类、标签、关键词筛选
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
category_id |
int | 可选 | 分类ID |
tag |
string | 可选 | 标签名或slug |
q |
string | 可选 | 关键词搜索(标题/摘要) |
page |
int | 可选 | 页码,默认1 |
per_page |
int | 可选 | 每页数量,默认10,最大50 |
调用示例
curl -X GET "https://api.cnhk.net/api/v1/documents?category_id=示例值" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"total": 100,
"page": 1,
"per_page": 10,
"data": [
{
"id": 1,
"title": "文档标题",
"summary": "摘要...",
"category": "PHP安全",
"tags": [
"安全",
"PHP"
],
"view_count": 120,
"created_at": "2026-01-01T00:00:00Z",
"url": "https:\/\/zsd.cnhk.net\/article\/1"
}
]
}
GET
/api/v1/documents/{id}
获取文档详情
获取单个文档的完整信息,包括分类、标签和块级内容
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
int | 必填 | 文档ID(路径参数) |
调用示例
curl -X GET "https://api.cnhk.net/api/v1/documents/{id}" \
-H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"data": {
"id": 1,
"title": "文档标题",
"summary": "摘要",
"category": "PHP安全",
"tags": [
"安全"
],
"view_count": 120,
"blocks": [
{
"type": "heading",
"content": "标题"
},
{
"type": "paragraph",
"content": "正文"
}
],
"created_at": "...",
"updated_at": "..."
}
}
GET
/api/v1/categories
获取分类列表
获取所有文档分类及其文档数量
调用示例
curl -X GET "https://api.cnhk.net/api/v1/categories" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"data": [
{
"id": 1,
"name": "PHP安全",
"slug": "php-security",
"description": "PHP安全相关文档",
"documents_count": 42
}
]
}
POST
/api/v1/chat
AI知识库问答
基于知识库检索 + LLM 生成的智能问答,返回答案和引用来源
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
message |
string | 必填 | 用户问题 |
model |
string | 可选 | 回答模式:precise(精准)/comprehensive(全面)/concise(简洁)/detailed(详细),默认comprehensive |
调用示例
curl -X POST "https://api.cnhk.net/api/v1/chat" \
-H "X-API-Key: hk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"message":"什么是SQL注入?","model":"comprehensive"}'
响应示例
{
"success": true,
"answer": "AI生成的回答内容...",
"model": "comprehensive",
"is_llm": true,
"tokens_used": 256,
"sources": [
{
"document_id": 1,
"title": "文档标题",
"similarity": 0.92,
"url": "https:\/\/zsd.cnhk.net\/article\/1"
}
]
}
POST
/api/v1/rag
RAG增强问答
检索增强生成,返回答案、检索上下文和来源,可控制检索数量和是否重排序
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
query |
string | 必填 | 查询问题 |
top_k |
int | 可选 | 检索数量,默认5,最大20 |
use_rerank |
bool | 可选 | 是否使用重排序,默认true |
调用示例
curl -X POST "https://api.cnhk.net/api/v1/rag" \
-H "X-API-Key: hk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"query":"PHP安全最佳实践","top_k":5,"use_rerank":true}'
响应示例
{
"success": true,
"query": "问题",
"answer": "RAG生成的答案",
"retrieval_count": 5,
"contexts": [
{
"document_id": 1,
"title": "文档标题",
"content": "片段内容",
"similarity": 0.92
}
],
"sources": []
}
POST
/api/v1/document/parse
文档解析
上传文档文件或提供URL,异步解析为结构化内容
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
url |
string | 可选 | 文档URL(与file二选一) |
file |
file | 可选 | 上传的文档文件(与url二选一) |
调用示例
curl -X POST "https://api.cnhk.net/api/v1/document/parse" \ -H "X-API-Key: hk_your_api_key_here" \ -F "file=@/path/to/document.pdf"
响应示例
{
"success": true,
"message": "文档解析任务已创建",
"task_id": "parse_65a1b2c3d4e5f",
"status": "processing"
}
POST
/api/v1/document/ocr
OCR文字识别
上传图片,识别其中的文字内容,返回文本、置信度和块级位置
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
image |
file | 必填 | 图片文件(jpg/png/webp) |
调用示例
curl -X POST "https://api.cnhk.net/api/v1/document/ocr" \ -H "X-API-Key: hk_your_api_key_here" \ -F "image=@/path/to/image.jpg"
响应示例
{
"success": true,
"text": "识别出的文字内容...",
"engine": "native",
"confidence": 0.95,
"blocks": [
{
"text": "块文字",
"bbox": [
0,
0,
100,
30
]
}
]
}
GET
/api/v1/vector/query
向量查询
基于文本向量相似度检索知识库片段,返回文档ID、块ID和相似度
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
text |
string | 必填 | 查询文本 |
limit |
int | 可选 | 返回数量,默认5,最大20 |
调用示例
curl -X GET "https://api.cnhk.net/api/v1/vector/query?text=示例值" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"query": "关键词",
"engine": "keyword_fallback",
"results": [
{
"document_id": 1,
"chunk_id": 10,
"title": "文档标题",
"content": "片段内容",
"similarity": 0.88
}
]
}
GET
/api/v1/usage
用量查询
查询当前 API 密钥的配额使用情况、余额和套餐信息
调用示例
curl -X GET "https://api.cnhk.net/api/v1/usage" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"success": true,
"api_key": "hk_xxx",
"plan": "professional",
"rate_limit": 300,
"daily_quota": 10000,
"daily_used": 120,
"daily_remaining": 9880,
"monthly_quota": 300000,
"monthly_used": 5000,
"monthly_remaining": 295000,
"total_calls": 15000,
"balance": 100
}
GET
/api/health
健康检查
检查 API 服务状态,无需认证
调用示例
curl -X GET "https://api.cnhk.net/api/health" \ -H "X-API-Key: hk_your_api_key_here"
响应示例
{
"status": "ok",
"service": "弘客智囊 API",
"version": "v1.0",
"time": "2026-01-01T00:00:00Z"
}
在线调试器
无需写代码,直接在浏览器中测试 API 接口
密钥仅在本地浏览器使用,不会上传到服务器
点击「发送请求」查看响应...
官方 SDK
一键集成,开箱即用
变更日志
v1.0.0
2026-09-01
正式发布
- 发布知识库检索、文档列表/详情、分类列表接口
- 发布 AI 知识库问答(chat)和 RAG 增强问答(rag)接口
- 发布文档解析(parse)、OCR 识别(ocr)、向量查询(vector/query)接口
- 发布用量查询(usage)和健康检查(health)接口
- API 密钥管理、限流、计费系统上线
v0.9.0-beta
2026-08-15
内测
- API 平台内测版本,开放基础检索和问答接口