从注册到完成首次 API 调用,只需 5 分钟
在助手详情页 → API 接入 Tab → 创建 API Key。记录 assistantId 和 jk-xxxx 格式的 Key。
jk-xxxxxxxxxxxxxxxx
# 获取助手信息,验证 Key 是否有效
curl https://know.jitword.com/open/v1/info \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx"
返回 200 及助手信息则表示 Key 有效,可以继续下一步。
curl -X POST https://know.jitword.com/open/v1/chat \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"message":"产品有哪些核心功能?"}' \
--no-buffer
# 响应:SSE 流式输出
event: conversation_meta
data: {"conversation_id":"conv_xxx"}
event: block_delta
data: {"delta":"本产品核心功能包括..."}
event: block_replace
data: {"blocks":[{"type":"text","content":"完整回答内容..."}]}
悬浮气泡适合全局服务,iframe 适合页面内嵌
<script>
window.JitMindConfig = {
assistantId: 'your-assistant-id',
token: 'jk-xxxxxxxxxxxxxxxx',
baseUrl: 'https://know.jitword.com',
btnLabel: '智能助手', // 按钮文案
btnColor: '#6366F1', // 按钮颜色
theme: 'light', // 'light' | 'dark'
position: 'bottom-right'
}
</script>
<script src="https://know.jitword.com/know/embed.js"></script>
<iframe
src="https://know.jitword.com/know/embed/{assistantId}
?key=jk-xxxxxxxxxxxxxxxx&theme=light"
width="400"
height="600"
style="border:none;border-radius:16px;
box-shadow:0 4px 24px rgba(0,0,0,0.12)"
allow="clipboard-write"
></iframe>
将 {assistantId} 和 jk-xxx 替换为你的真实值即可。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| assistantId | string | 必填 | — | AI 助手的唯一 ID |
| token | string | 必填 | — | API Key,格式为 jk-xxx |
| baseUrl | string | 可选 | script origin | API 服务地址,私有化部署时需指定 |
| theme | 'light'|'dark' | 可选 | 'light' | 界面主题,浅色或深色 |
| position | 'bottom-right'|'bottom-left' | 可选 | 'bottom-right' | 悬浮按钮位置 |
| btnColor | string | 可选 | '#6366F1' | 悬浮按钮颜色(CSS 颜色值) |
| btnLabel | string | 可选 | '智能助手' | 悬浮按钮文案 |
| width | number | 可选 | 380 | 面板宽度(px,PC 端) |
| height | number | 可选 | 600 | 面板高度(px,PC 端) |
Base URL: https://know.jitword.com/open/v1
所有 API 请求均需在 Header 中携带 API Key:
Authorization: Bearer jk-xxxxxxxxxxxxxxxx/info
获取助手信息
获取当前 API Key 绑定的助手信息,可用于初始化欢迎语、助手名称展示等。
curl https://know.jitword.com/open/v1/info \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx"{
"id": "asst_abc123",
"name": "产品知识库助手",
"description": "负责解答产品相关问题",
"welcomeMessage": "你好!我是产品助手,有什么可以帮你?"
}/chat
发起对话(SSE 流式)
向助手发送消息并获取 SSE 流式回复。支持多轮对话,服务端推送事件格式。
{
"message": "如何申请退款?",
// 可选,续接多轮对话
"conversationId": "conv_xxx"
}Authorization: Bearer jk-xxx
Content-Type: application/json
Accept: text/event-stream| 事件名 | 数据字段 | 说明 |
|---|---|---|
| conversation_meta | conversation_id | 返回对话 ID,用于续接多轮对话 |
| block_start | — | 新内容块开始,可用于显示 loading |
| block_delta | delta | 流式增量文本,每帧追加到展示区域 |
| block_replace | blocks[0].content | 完整最终内容,用于替换流式展示结果 |
[DONE] | — | 流结束标志,关闭连接 |
选择你熟悉的语言,直接复制使用
# 1. 获取助手信息
curl https://know.jitword.com/open/v1/info \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx"
# 2. 发起流式对话
curl -X POST https://know.jitword.com/open/v1/chat \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"message":"产品有哪些核心功能?"}' \
--no-buffer
# 3. 多轮对话(续接)
curl -X POST https://know.jitword.com/open/v1/chat \
-H "Authorization: Bearer jk-xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"message":"能详细说说第一点吗?","conversationId":"conv_xxx"}' \
--no-buffer
// JitKnow SSE 流式对话 - JavaScript 示例
const askAssistant = async (message, conversationId) => {
const response = await fetch('https://know.jitword.com/open/v1/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer jk-xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({ message, conversationId })
})
const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
let currentEvent = '' // 跨行追踪事件类型
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
const lines = buffer.split('\n')
buffer = lines.pop() || ''
for (const line of lines) {
if (line.startsWith('event: ')) {
currentEvent = line.slice(7).trim(); continue
}
if (!line.trim()) { currentEvent = ''; continue }
if (!line.startsWith('data: ')) continue
const raw = line.slice(6).trim()
if (!raw || raw === '[DONE]') continue
const data = JSON.parse(raw)
if (currentEvent === 'block_delta') {
document.getElementById('output').textContent += data.delta
}
if (currentEvent === 'block_replace') {
document.getElementById('output').textContent = data.blocks[0].content
}
}
}
}
askAssistant('产品有哪些核心功能?')
# JitKnow SSE 流式对话 - Python 示例
import requests
import json
API_KEY = "jk-xxxxxxxxxxxxxxxx"
BASE_URL = "https://know.jitword.com/open/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 获取助手信息
def get_info():
resp = requests.get(f"{BASE_URL}/info", headers=HEADERS)
return resp.json()
# 流式对话(SSE)
def chat_stream(message, conversation_id=None):
body = {"message": message}
if conversation_id:
body["conversationId"] = conversation_id
with requests.post(
f"{BASE_URL}/chat",
headers={**HEADERS, "Content-Type": "application/json"},
json=body,
stream=True
) as resp:
current_event = ""
for line in resp.iter_lines(decode_unicode=True):
if line.startswith("event: "):
current_event = line[7:].strip()
elif line.startswith("data: "):
raw = line[6:].strip()
if not raw or raw == "[DONE]": continue
data = json.loads(raw)
if current_event == "block_delta":
print(data["delta"], end="", flush=True)
elif current_event == "block_replace":
print() # 换行
elif not line:
current_event = ""
# 使用示例
info = get_info()
print(f"助手名称:{info['name']}")
chat_stream("产品有哪些核心功能?")
登录 JitKnow,创建助手,在「API 接入」Tab 下载本地 Demo,5 分钟内跑通完整效果
在助手「API 接入」Tab 下载预配置好的演示 HTML,浏览器直接打开即可测试气泡模式或 iframe 模式。
Demo HTML 中已预置助手 ID,将 token 字段替换为你的 Key,即可完整体验问答、流式输出全流程。
Demo 是标准 HTML 文件,可直接查看源码,快速理解接入方式,复制到你的项目中二次开发。
这就是接入后,用户在你的页面看到的效果
从 Key 权限到调用频次,全方位保障你的 API 服务稳定安全
接入过程中最常遇到的问题与解答
baseUrl 和 API 调用地址改为你的私有服务地址(如 https://your-domain.com)即可。详见私有化部署文档。/chat 接口统一使用 SSE 流式输出,AI 生成的内容实时推送,用户可看到逐字输出效果,体验更流畅。block_replace 事件,该事件携带最终完整内容,关闭连接后处理即可。block_replace 事件的 blocks 数组中包含 citations 字段,列出每条引用的文档名称、页码和原文片段,你可以在 UI 中展示「参考来源」,提升用户信任度。HTTP 429 Too Many Requests,响应体包含 {"message":"Rate limit exceeded"}。建议在前端做友好提示,如「服务繁忙,请稍后再试」。配额会在每天 0 点(UTC+8)自动重置,RPM 限流为滑动窗口实时重置。