开发者文档 v1.0

弘客开放平台 API

知识库检索 · AI问答 · RAG增强 · 文档解析 · OCR识别 · 向量查询

快速入门

3 步完成你的第一次 API 调用

1

注册账号

访问 api.cnhk.net 注册并登录

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/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 接口

密钥仅在本地浏览器使用,不会上传到服务器

点击「发送请求」查看响应...

变更日志

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 平台内测版本,开放基础检索和问答接口