API 文档 - 灵知 LingZhi

快速开始

商业化说明：API 用于把已验证的「知识库问答」接入业务系统。免费版默认不含生产级 API；专业版 / 团队版可按配额开通；企业版可合同定制限流与 SLA。建议先在 Web 端完成首次可引用问答，再接入生产。详见套餐页 · 开放平台 · 帮助中心。

1

确认套餐权益并获取 API 密钥

前往开放平台创建密钥。密钥只显示一次，请仅保存在服务端。开发 / 生产环境请拆分密钥。

2

选择对接方式

优先对接知识库检索 + 对话。可直接使用 HTTP；SDK 示例见下方或登录后打开开发者门户。工作流 / 插件 / 多模态为后置能力。

3

发起第一个请求

推荐认证头：Authorization: Bearer <API_KEY>（部分接口兼容 X-API-Key）。请处理 401/403/429/502/504。

curl Python Node.js Java PHP

# 上传文件并处理
curl -X POST "/api/v1/upload" \
  -H "X-API-Key: sk-your-key" \
  -F "file=@document.pdf" \
  -F "prompt=请总结要点"

import requests

url = "/api/v1/upload"
headers = {"X-API-Key": "sk-your-key"}

with open("document.pdf", "rb") as f:
    resp = requests.post(url, headers=headers, files={"file": f}, data={"prompt": "请总结要点"})

print(resp.json())

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('file', fs.createReadStream('document.pdf'));
form.append('prompt', '请总结要点');

const resp = await fetch('/api/v1/upload', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk-your-key', ...form.getHeaders() },
  body: form
});
const data = await resp.json();
console.log(data);

OkHttpClient client = new OkHttpClient();

RequestBody body = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("file", "document.pdf",
        RequestBody.create(new File("document.pdf"), MediaType.parse("application/pdf")))
    .addFormDataPart("prompt", "请总结要点")
    .build();

Request req = new Request.Builder()
    .url("/api/v1/upload")
    .addHeader("X-API-Key", "sk-your-key")
    .post(body)
    .build();

Response resp = client.newCall(req).execute();
System.out.println(resp.body().string());

<?php
$ch = curl_init('/api/v1/upload');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: sk-your-key'],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('document.pdf'),
        'prompt' => '请总结要点'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$resp = curl_exec($ch);
curl_close($ch);
print_r(json_decode($resp, true));

4

轮询获取结果

上传是异步处理的，使用返回的 task_id 轮询状态，完成后获取结果。

🔐 认证方式

开放平台 API 使用 X-API-Key 进行认证。所有 API 请求都需要在 Header 中携带此密钥。

💡 两种 Token 的区别：
• API Key（开放平台）— 通过 X-API-Key Header 传入，用于开发者集成，管理组件、对话、会话等。
• Embed Token（嵌入组件）— Widget 专用的公开 token，用于网页嵌入场景，不需要登录。
两者不通用，开放平台 API 统一使用 API Key。

HTTP Header

X-API-Key: sk-your-api-key-here

⚠️ 安全提示：请勿在客户端代码中硬编码 API Key，应通过环境变量或配置文件管理。泄露的密钥请立即在开放平台删除。

📦 SDK 下载

选择你熟悉的语言 SDK，快速接入 API。所有 SDK 内置重试、超时、错误处理。

🐍

Python SDK

pip install lingzhi-sdk · 支持 Python 3.8+

📗

Node.js SDK

npm install lingzhi-sdk · 支持 Node 16+

☕

Java SDK

Maven / Gradle · 支持 Java 8+

🐘

PHP SDK

composer require lingzhi/sdk · 支持 PHP 7.4+

🐹

Go SDK

go get lingzhi-sdk · 支持 Go 1.18+

📜

cURL 示例集

所有接口的 cURL 示例，可直接运行

POST /api/v1/upload

上传文件并提交处理任务。支持音频、视频、文档、图片等格式。文件大小限制 100MB。

请求参数

参数	类型	必填	说明
file	File	必填	上传的文件（multipart/form-data）
prompt	string	可选	处理提示词，如"请总结要点"

代码示例

curl Python Node.js

curl -X POST "/api/v1/upload" \
  -H "X-API-Key: sk-your-key" \
  -F "file=@recording.mp3" \
  -F "prompt=请总结要点"

resp = requests.post(
    "/api/v1/upload",
    headers={"X-API-Key": "sk-your-key"},
    files={"file": open("recording.mp3", "rb")},
    data={"prompt": "请总结要点"}
)
print(resp.json())
# {"task_id": "abc123...", "status": "pending"}

const form = new FormData();
form.append('file', fs.createReadStream('recording.mp3'));
form.append('prompt', '请总结要点');

const resp = await fetch('/api/v1/upload', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk-your-key', ...form.getHeaders() },
  body: form
});

响应示例

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "文件已上传，正在处理"
}

🧪 在线测试

API Key

文件

Prompt

GET /api/v1/tasks/{task_id}

查询任务处理状态。状态包括：pending（等待）、processing（处理中）、done（完成）、error（失败）。

路径参数

参数	类型	必填	说明
task_id	string	必填	上传接口返回的任务 ID

代码示例

curl Python Node.js

curl "/api/v1/tasks/{task_id}" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    f"/api/v1/tasks/{task_id}",
    headers={"X-API-Key": "sk-your-key"}
)
print(resp.json())
# {"task_id": "...", "status": "done", "progress": 100}

const resp = await fetch(`/api/v1/tasks/${taskId}`, {
  headers: { 'X-API-Key': 'sk-your-key' }
});
const data = await resp.json();

响应示例

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "done",
  "progress": 100,
  "file_name": "recording.mp3",
  "task_type": "transcribe",
  "created_at": "2026-06-22T10:30:00Z"
}

GET /api/v1/tasks/{task_id}/result

获取任务的完整处理结果。仅当任务状态为 done 时可调用。

curl Python

curl "/api/v1/tasks/{task_id}/result" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    f"/api/v1/tasks/{task_id}/result",
    headers={"X-API-Key": "sk-your-key"}
)
result = resp.json()
print(result["result"])  # 处理结果文本

响应示例

{
  "task_id": "a1b2c3d4...",
  "status": "done",
  "result": "会议纪要：1. 讨论了Q3目标...",
  "tokens_used": 1520,
  "model": "gpt-4o"
}

GET /api/v1/tasks

列出所有任务记录，支持分页。

查询参数

参数	类型	必填	说明
limit	int	可选	返回数量，默认 20，最大 100
offset	int	可选	偏移量，用于分页

curl Python

curl "/api/v1/tasks?limit=20" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    "/api/v1/tasks",
    headers={"X-API-Key": "sk-your-key"},
    params={"limit": 20}
)
for task in resp.json()["tasks"]:
    print(task["task_id"], task["status"])

GET /api/v1/knowledge/bases

获取当前用户的所有知识库，支持分页。

curl Python

curl "/api/v1/knowledge/bases?page=1&page_size=20" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    "/api/v1/knowledge/bases",
    headers={"X-API-Key": "sk-your-key"},
    params={"page": 1, "page_size": 20}
)
for kb in resp.json()["knowledge_bases"]:
    print(kb["id"], kb["name"])

响应示例

{
  "knowledge_bases": [{"id": 1, "name": "产品文档", "doc_count": 15, ...}],
  "total": 3, "page": 1, "page_size": 20
}

POST /api/v1/knowledge/bases

创建一个新的知识库。

请求体

参数	类型	必填	说明
name	string	必填	知识库名称
description	string	可选	描述
kb_type	string	可选	类型：text / database，默认 text

curl

curl -X POST "/api/v1/knowledge/bases" \
  -H "X-API-Key: sk-your-key" -H "Content-Type: application/json" \
  -d '{"name": "产品文档", "description": "产品相关文档"}'

GET/api/v1/knowledge/bases/{kb_id}

获取指定知识库的详细信息。

DELETE/api/v1/knowledge/bases/{kb_id}

删除指定知识库及其所有文档。

GET/api/v1/knowledge/bases/{kb_id}/documents

获取知识库中的文档列表，支持分页。

curl

curl "/api/v1/knowledge/bases/1/documents" \
  -H "X-API-Key: sk-your-key"

POST/api/v1/knowledge/bases/{kb_id}/search

在知识库中搜索相关内容，返回匹配的文本片段及相似度分数。

请求体

参数	类型	必填	说明
query	string	必填	搜索关键词
top_k	int	可选	返回结果数量，默认 5

curlPython

curl -X POST "/api/v1/knowledge/bases/1/search" \
  -H "X-API-Key: sk-your-key" -H "Content-Type: application/json" \
  -d '{"query": "退货政策", "top_k": 5}'

resp = requests.post(
    "/api/v1/knowledge/bases/1/search",
    headers={"X-API-Key": "sk-your-key"},
    json={"query": "退货政策", "top_k": 5}
)
for r in resp.json()["results"]:
    print(r["content"][:80], r["score"])

响应示例

{
  "results": [
    {"content": "自收到商品之日起7天内可申请退货...", "score": 0.92, "filename": "退货政策.pdf"}
  ],
  "query": "退货政策"
}

GET/api/v1/conversations

获取当前用户的对话列表，支持分页。

curl

curl "/api/v1/conversations" -H "X-API-Key: sk-your-key"

POST/api/v1/conversations

创建新对话。

请求体

参数	类型	必填	说明
title	string	可选	对话标题
kb_id	int	可选	绑定知识库 ID

GET/api/v1/conversations/{conv_id}/messages

获取指定对话的消息历史。

POST/api/v1/conversations/{conv_id}/chat

在对话中发送消息并获取 AI 回复（基于绑定知识库的 RAG 对话）。

请求体

参数	类型	必填	说明
message	string	必填	用户消息
kb_id	int	可选	指定知识库（覆盖对话默认绑定）

curlPython

curl -X POST "/api/v1/conversations/1/chat" \
  -H "X-API-Key: sk-your-key" -H "Content-Type: application/json" \
  -d '{"message": "你们的退货政策是什么？"}'

resp = requests.post(
    "/api/v1/conversations/1/chat",
    headers={"X-API-Key": "sk-your-key"},
    json={"message": "你们的退货政策是什么？"}
)
print(resp.json()["reply"])

POST/api/chat/upload

上传聊天附件（图片/文档/音频/视频），返回附件信息用于后续消息发送。支持的格式：图片(jpg/png/gif/webp)、文档(pdf/doc/docx/xls/xlsx/ppt/pptx/txt/md/csv)、音频(mp3/wav/ogg/m4a)、视频(mp4/webm/mov)。最大50MB。

请求格式

Content-Type: multipart/form-data

参数	类型	必填	说明
file	file	必填	要上传的文件

响应

{
  "url": "/static/chat_attachments/abc123.pdf",
  "filename": "报告.pdf",
  "content_type": "application/pdf",
  "size": 102400,
  "category": "document",
  "text_preview": "文档提取的文本内容（前2000字）..."
}

在消息中使用附件

// 1. 先上传附件
const formData = new FormData();
formData.append('file', file);
const attResp = await fetch('/api/chat/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
  body: formData
});
const attachment = await attResp.json();

// 2. 发送消息时带上附件
const chatResp = await fetch('/api/chat/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' },
  body: JSON.stringify({
    query: '请分析这个文件',
    kb_id: 1,
    attachments: [attachment]
  })
});

GET/api/v1/models

获取当前用户可用的模型列表。

GET/api/v1/providers

获取所有可用的模型供应商。

GET/api/v1/workflows

获取当前用户的工作流列表。

POST/api/v1/workflows/{workflow_id}/run

运行指定的工作流，传入输入数据获取执行结果。

GET/api/v1/plugins

获取已安装的插件列表。

GET/api/v1/data-sources

获取当前用户的数据源列表。

POST/api/v1/data-sources/{source_id}/sync

触发指定数据源的同步任务。

POST/api/v1/multimodal/analyze

分析图片内容，支持场景识别、文字提取、物体检测等。

POST/api/v1/multimodal/tts

将文字转换为语音，返回 Base64 编码的音频数据。

GET /api/v1/embed/configs

列出当前用户的所有嵌入组件配置。

curl Python Node.js

curl "/api/v1/embed/configs" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    "/api/v1/embed/configs",
    headers={"X-API-Key": "sk-your-key"}
)
for cfg in resp.json():
    print(cfg["id"], cfg["title"])

const resp = await fetch('/api/v1/embed/configs', {
  headers: { 'X-API-Key': 'sk-your-key' }
});
const configs = await resp.json();

响应示例

[
  {
    "id": 1,
    "title": "AI 助手",
    "embed_token": "TF0Js8J0X7k...",
    "is_enabled": true,
    "total_sessions": 42,
    "total_messages": 156
  }
]

POST /api/v1/embed/configs

创建一个新的嵌入组件配置。

请求体参数

参数	类型	必填	说明
title	string	可选	组件标题，默认 "AI 助手"
kb_id	int	可选	绑定知识库 ID，不绑定则用户可切换
theme_color	string	可选	主题色，默认 "#6366f1"
welcome_message	string	可选	欢迎语

curl Python

curl -X POST "/api/v1/embed/configs" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "客服助手", "theme_color": "#10b981"}'

resp = requests.post(
    "/api/v1/embed/configs",
    headers={"X-API-Key": "sk-your-key"},
    json={"title": "客服助手", "theme_color": "#10b981"}
)
print(resp.json()["id"])  # 新配置 ID

GET /api/v1/embed/configs/{config_id}

获取指定嵌入组件的完整配置信息。

curl Python

curl "/api/v1/embed/configs/{config_id}" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    f"/api/v1/embed/configs/{config_id}",
    headers={"X-API-Key": "sk-your-key"}
)
cfg = resp.json()
print(cfg["title"], cfg["embed_token"])

PUT /api/v1/embed/configs/{config_id}

更新嵌入组件配置。只需传入要修改的字段。

curl Python

curl -X PUT "/api/v1/embed/configs/{config_id}" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "新标题", "theme_color": "#ef4444"}'

resp = requests.put(
    f"/api/v1/embed/configs/{config_id}",
    headers={"X-API-Key": "sk-your-key"},
    json={"title": "新标题", "theme_color": "#ef4444"}
)

DELETE /api/v1/embed/configs/{config_id}

删除指定的嵌入组件配置。关联的会话和消息将一并删除。

curl Python

curl -X DELETE "/api/v1/embed/configs/{config_id}" \
  -H "X-API-Key: sk-your-key"

resp = requests.delete(
    f"/api/v1/embed/configs/{config_id}",
    headers={"X-API-Key": "sk-your-key"}
)
print(resp.status_code)  # 200

GET /api/v1/embed/configs/{config_id}/sessions

列出指定组件的所有会话记录，支持分页。

curl Python

curl "/api/v1/embed/configs/{config_id}/sessions?limit=20" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    f"/api/v1/embed/configs/{config_id}/sessions",
    headers={"X-API-Key": "sk-your-key"},
    params={"limit": 20}
)
for s in resp.json():
    print(s["session_id"], s["visitor_name"])

GET /api/v1/embed/configs/{config_id}/sessions/{session_id}/messages

获取指定会话的消息历史记录。

curl Python

curl "/api/v1/embed/configs/{config_id}/sessions/{session_id}/messages" \
  -H "X-API-Key: sk-your-key"

resp = requests.get(
    f"/api/v1/embed/configs/{config_id}/sessions/{session_id}/messages",
    headers={"X-API-Key": "sk-your-key"}
)
for msg in resp.json():
    print(msg["role"], msg["content"][:50])

POST /api/v1/embed/chat

发起 RAG 对话（非流式）。基于绑定的知识库进行检索增强生成，返回完整回答。

请求体参数

参数	类型	必填	说明
embed_id	int	必填	嵌入组件配置 ID（通过 GET /embed/configs 获取）
message	string	必填	用户消息内容
kb_id	int	可选	指定知识库 ID（覆盖组件默认绑定）
session_id	string	可选	会话 ID，不传则自动创建
attachments	array	可选	附件列表，每项包含 url/filename/content_type/size/category/text_preview（先通过上传接口获取）

curl Python Node.js

curl -X POST "/api/v1/embed/chat" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "embed_id": 1,
    "message": "你们的退货政策是什么？",
    "kb_id": 5
  }'

resp = requests.post(
    "/api/v1/embed/chat",
    headers={"X-API-Key": "sk-your-key"},
    json={
        "embed_id": 1,
        "message": "你们的退货政策是什么？",
        "kb_id": 5
    }
)
data = resp.json()
print(data["reply"])
print(data["sources"])  # 引用来源

const resp = await fetch('/api/v1/embed/chat', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk-your-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embed_id: 1,
    message: '你们的退货政策是什么？',
    kb_id: 5
  })
});
const data = await resp.json();
console.log(data.reply);

响应示例

{
  "reply": "我们的退货政策如下：自收到商品之日起7天内...",
  "session_id": "sess_abc123",
  "sources": [
    { "filename": "退货政策.pdf", "score": 0.92 }
  ],
  "tokens_used": 320
}

🧪 在线测试

API Key

Embed ID

消息

POST /api/v1/embed/chat/stream

发起 RAG 流式对话（SSE）。与 /embed/chat 参数相同，但响应为 Server-Sent Events 流。

curl Python Node.js

curl -X POST "/api/v1/embed/chat/stream" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"embed_id": 1, "message": "你好"}'

resp = requests.post(
    "/api/v1/embed/chat/stream",
    headers={"X-API-Key": "sk-your-key", "Accept": "text/event-stream"},
    json={"embed_id": 1, "message": "你好"},
    stream=True
)
for line in resp.iter_lines():
    if line:
        print(line.decode())

const resp = await fetch('/api/v1/embed/chat/stream', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk-your-key',
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ embed_id: 1, message: '你好' })
});
const reader = resp.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

SSE 事件格式

data: {"type": "chunk", "content": "你好"}

data: {"type": "chunk", "content": "！有什么"}

data: {"type": "chunk", "content": "可以帮您？"}

data: {"type": "sources", "sources": [{"filename": "FAQ.pdf", "score": 0.89}]}

data: {"type": "done", "session_id": "sess_abc123", "tokens_used": 128}

POST /api/v1/embed/tts

将文字转换为语音，返回音频流。支持多种语言和音色。

请求体参数

参数	类型	必填	说明
text	string	必填	要转换的文本内容
voice	string	可选	音色名称，默认 "zh-CN-XiaoxiaoNeural"
speed	float	可选	语速，范围 0.5-2.0，默认 1.0

curl Python

curl -X POST "/api/v1/embed/tts" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "你好，有什么可以帮您？"}' \
  --output speech.mp3

resp = requests.post(
    "/api/v1/embed/tts",
    headers={"X-API-Key": "sk-your-key"},
    json={"text": "你好，有什么可以帮您？"},
    stream=True
)
with open("speech.mp3", "wb") as f:
    for chunk in resp.iter_content(8192):
        f.write(chunk)

POST /api/embed/widget/{token}/upload

上传附件文件（图片/文档/音频/视频），返回附件信息用于聊天消息。最大20MB。支持 jpg/png/gif/webp/pdf/doc/docx/xls/xlsx/txt/md/csv/mp3/wav/mp4/webm 等格式。

响应

{
  "url": "/static/embed/abc123.pdf",
  "filename": "报告.pdf",
  "content_type": "application/pdf",
  "size": 102400,
  "category": "document",
  "text_preview": "文档提取的文本内容..."
}

curl Python

curl -X POST "/api/embed/widget/TOKEN/upload" \
  -F "file=@report.pdf"

resp = requests.post(
    "/api/embed/widget/TOKEN/upload",
    files={"file": open("report.pdf", "rb")}
)
attachment = resp.json()
print(attachment["url"], attachment["category"])

POST /api/v1/embed/rate

对消息进行评分（点赞/点踩），用于质量追踪和模型优化。

请求体参数

参数	类型	必填	说明
message_id	int	必填	消息 ID
rating	int	必填	评分：1（赞）或 -1（踩）
feedback	string	可选	文字反馈

curl Python

curl -X POST "/api/v1/embed/rate" \
  -H "X-API-Key: sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"message_id": 123, "rating": 1, "feedback": "回答很准确"}'

resp = requests.post(
    "/api/v1/embed/rate",
    headers={"X-API-Key": "sk-your-key"},
    json={"message_id": 123, "rating": 1, "feedback": "回答很准确"}
)