创雪 API · 客户端对接文档

Base URL：https://snowfure.com/api · 共 57 个接口 · 全部示例可直接复制运行

机读版：https://snowfure.com/api/v1/manifest · 速览版：https://snowfure.com/llms.txt

鉴权SSE 流式错误码 对话 · 模型/会话/记忆/收藏/制品 IM · 消息/任务/群/机器人插件 文档 · 知识库/草稿 管理 · 密钥/用户/统计
鉴权方式密钥三选一：查询串 ?key=… / 请求头 Authorization: Bearer … / X-API-Key: …
SSE 调用
对话入口https://snowfure.com/chat/

鉴权

{ "how": "密钥三选一：查询串 ?key=… / 请求头 Authorization: Bearer … / X-API-Key: …", "kinds": [ { "kind": "master", "ident": "owner", "desc": "主密钥（曾健本人，全权限，可颁发）", "where": "本机 ~/.hermes/.snowfure_live_key；控制台「接口 · 密钥」页可签发 sk_ 派生密钥" }, { "kind": "issued", "ident": "apikey:<名字>", "desc": "已颁发的 sk_… 密钥，按 scopes 限权", "scopes": [ "chat", "im", "docs", "admin" ] }, { "kind": "sso", "ident": "<open_id>", "desc": "飞书 SSO 令牌（?t=… 换来的会话令牌），只能看自己的数据" } ], "self_check": "GET /api/v1/whoami → {\"ok\":true,\"ident\":\"…\",\"name\":\"…\"}" }

SSE 流式对话

{ "endpoint": "POST /api/chat/stream", "content_type": "text/event-stream", "frame_format": "每帧一行 `data: <json>`，帧间空行", "events": [ { "frame": "{\"snowfure\":{\"conversation_id\":\"…\",\"recall\":{…}}}", "when": "首帧：会话 id + 本轮召回统计（记忆/本体命中数）" }, { "frame": "{\"choices\":[{\"delta\":{\"content\":\"字\"}}]}", "when": "逐字增量：把 content 依次拼接" }, { "frame": "{\"choices\":[{\"finish_reason\":\"stop\"}],\"usage\":{…}}", "when": "收尾帧（可能带 usage 用量）" }, { "frame": "[DONE]", "when": "流结束，客户端收到即停止读取" } ], "tips": [ "用 SSE 客户端逐行读 data:；遇 [DONE] 关闭连接", "首帧的 conversation_id 存下来，下次带上它就续上下文", "断线重连不会重复计费：重发同一 conversation_id 即可" ] }

错误码

[ { "http": 401, "code": "UNAUTHORIZED", "when": "缺密钥 / 密钥错 / 已吊销" }, { "http": 403, "code": "FORBIDDEN", "when": "身份没有该范围的数据权限" }, { "http": 403, "code": "DEMO_DENIED", "when": "演示身份调用了本地数据接口（只放开模型对话与网络数据）" }, { "http": 404, "code": "NOT_FOUND", "when": "对象不存在（会话/草稿/本体对象…）" }, { "http": 400, "code": "BAD_ACTION", "when": "action 参数不认识" }, { "http": 500, "code": "SAVE_FAIL / UPLOAD_FAIL / ASR_FAIL / MCP_FAIL / ARTS_FAIL", "when": "对应模块内部错误，error 字段有原因" } ]

对话 · 模型/会话/记忆/收藏/制品chat · 33 个接口

POSThttps://snowfure.com/api/chat/streamchat_stream
流式对话（SSE 逐字返回） · 参数：model, messages
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/stream?key=$KEY' -H 'Content-Type: application/json' -d '{"model": "glm-5.3", "messages": [{"role": "user", "content": "你好"}], "conversation_id": "", "recall": {"mode": "auto", "layers": ["essence", "summary"]}}'
请求体结构
{
 "model": "glm-5.3",
 "messages": [
  {
   "role": "user",
   "content": "你好"
  }
 ],
 "conversation_id": "",
 "recall": {
  "mode": "auto",
  "layers": [
   "essence",
   "summary"
  ]
 }
}
返回示例 / 结构
SSE 流（帧格式见 manifest.sse）
POSThttps://snowfure.com/api/chat/runchat_run
一次性问答（非流式） · 参数：model, messages
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/run?key=$KEY' -H 'Content-Type: application/json' -d '{"model": "glm-5.3", "messages": [{"role": "user", "content": "你好"}]}'
请求体结构
{
 "model": "glm-5.3",
 "messages": [
  {
   "role": "user",
   "content": "你好"
  }
 ]
}
返回示例 / 结构
{"ok":true,"reply":"…"}
GEThttps://snowfure.com/api/chat/conversationslist_conversations
查 · 列出会话（按最近更新倒序，带 id/标题/模型/时间） · 参数：limit?
curl 示例
curl -s 'https://snowfure.com/api/chat/conversations?key=$KEY&limit=…'
GEThttps://snowfure.com/api/chat/conversationget_conversation
查 · 读一个会话的全部消息（含角色/内容/时间） · 参数：id
curl 示例
curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'
POSThttps://snowfure.com/api/chat/conversationscreate_conversation
增 · 新建空会话（返回新会话 id，可先起标题） · 参数：title?, model?
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/conversations?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/chat/renamerename_conversation
改 · 重命名会话标题（最长 60 字） · 参数：id, title
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'
DELETEhttps://snowfure.com/api/chat/conversationdelete_conversation
删 · 删除会话（软删除，可在回收站恢复） · 参数：id
curl 示例
curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'
POSThttps://snowfure.com/api/chat/conversations/deletedelete_conversations
删 · 批量删除多个会话（软删除，可回滚） · 参数：ids（数组或逗号分隔，最多 200 个）
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/conversations/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/chat/insightsextract_insights
洞察 · 从多个会话原文里提取事实/决策/方法/待办/金句（异步：返回 job_id） · 参数：ids（数组或逗号串）, prompt?（额外要求）
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/insights?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/chat/insights/resultinsight_result
查 · 取洞察提取结果（轮询，模型要跑 40-90 秒） · 参数：job_id
curl 示例
curl -s 'https://snowfure.com/api/chat/insights/result?key=$KEY&job_id=…'
GEThttps://snowfure.com/api/chat/conversations/trashlist_deleted_conversations
查 · 回收站：列出被删的会话（可恢复）
curl 示例
curl -s 'https://snowfure.com/api/chat/conversations/trash?key=$KEY'
POSThttps://snowfure.com/api/chat/conversations/restorerestore_conversations
改 · 从回收站恢复会话（回滚误删） · 参数：ids
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/conversations/restore?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/chat/conversations/purgepurge_conversations
彻底清除（仅回收站内，不可恢复） · 参数：ids
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/conversations/purge?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/chat/taskscreate_task
增 · 新建提醒/推送任务（一次性 / 每天 / 每 N 分钟） · 参数：action=add, title, body, mode, at_time, repeat, channel
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/chat/tasksdelete_task
删 · 删除任务 · 参数：action=delete, id
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/chat/task/runstask_runs
查 · 执行记录（每次投递的通道与回执） · 参数：limit?
curl 示例
curl -s 'https://snowfure.com/api/chat/task/runs?key=$KEY&limit=…'
GEThttps://snowfure.com/api/chat/artslist_arts
汇总全部制品（图/文档）
curl 示例
curl -s 'https://snowfure.com/api/chat/arts?key=$KEY'
GEThttps://snowfure.com/api/chat/agentslist_agents
智能体清单
curl 示例
curl -s 'https://snowfure.com/api/chat/agents?key=$KEY'
GEThttps://snowfure.com/api/chat/sopget_sop
读取 SOP 流程
curl 示例
curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'
GEThttps://snowfure.com/api/chat/onto/schemaonto_schema
本体对象类型（W3C 类层次+属性） · 参数：scope?
curl 示例
curl -s 'https://snowfure.com/api/chat/onto/schema?key=$KEY&scope=…'
GEThttps://snowfure.com/api/chat/onto/graphonto_graph
本体对象子图（节点+关系） · 参数：type?, q?, hops?
curl 示例
curl -s 'https://snowfure.com/api/chat/onto/graph?key=$KEY&type=…'
GEThttps://snowfure.com/api/chat/onto/objectonto_object
本体单个对象详情（属性+链接） · 参数：uri
curl 示例
curl -s 'https://snowfure.com/api/chat/onto/object?key=$KEY&uri=…'
GEThttps://snowfure.com/api/chat/ontoonto_stats
本体体检（文件/三元组/类/实例） · 参数：scope?
curl 示例
curl -s 'https://snowfure.com/api/chat/onto?key=$KEY&scope=…'
POSThttps://snowfure.com/api/chat/onto/queryonto_query
本体只读 SPARQL · 参数：sparql, scope?
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/onto/query?key=$KEY' -H 'Content-Type: application/json' -d '{"sparql": "SELECT ?s ?p ?o WHERE {?s ?p ?o} LIMIT 5"}'
请求体结构
{
 "sparql": "SELECT ?s ?p ?o WHERE {?s ?p ?o} LIMIT 5"
}
返回示例 / 结构
{"ok":true,"rows":[…]}"
POSThttps://snowfure.com/api/chat/onto/planonto_plan
本体驱动：意图→SPARQL→事实→计划 · 参数：intent, scope?
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/onto/plan?key=$KEY' -H 'Content-Type: application/json' -d '{"intent": "重启微信上传网关"}'
请求体结构
{
 "intent": "重启微信上传网关"
}
返回示例 / 结构
{"ok":true,"facts":[…],"steps":[…]}
POSThttps://snowfure.com/api/chat/onto/runonto_run
本体驱动：按事实下发智能体执行 · 参数：peer, intent, facts, steps
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/onto/run?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/chat/soplist_sop
SOP 流程列表+当前全文
curl 示例
curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'
POSThttps://snowfure.com/api/chat/sopsave_sop
保存/新建 SOP（action=save|new|delete|select） · 参数：action, id, name, text, auto
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/sop?key=$KEY' -H 'Content-Type: application/json' -d '{"action": "save", "id": "s…", "name": "流程名", "text": "第一步：… ｜ 参与：… ｜ 交付：… ｜ 验收：总督"}'
请求体结构
{
 "action": "save",
 "id": "s…",
 "name": "流程名",
 "text": "第一步：… ｜ 参与：… ｜ 交付：… ｜ 验收：总督"
}
返回示例 / 结构
{"ok":true}
POSThttps://snowfure.com/api/chat/sop/aisop_ai
AI 对话优化 SOP / 创建缺失智能体 · 参数：action=optimize|create, text, instruction, names
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/sop/ai?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/chat/draftslist_drafts
公众号草稿清单 · 参数：q, status
curl 示例
curl -s 'https://snowfure.com/api/chat/drafts?key=$KEY&q=…'
GEThttps://snowfure.com/api/chat/draftget_draft
读取草稿正文 · 参数：id
curl 示例
curl -s 'https://snowfure.com/api/chat/draft?key=$KEY&id=…'
POSThttps://snowfure.com/api/chat/uploadupload_file
附件上传 + 内容识别 · 参数：name, data, mime
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/upload?key=$KEY' -H 'Content-Type: application/json' -d '{"name": "a.png", "data": "<base64>", "mime": "image/png"}'
请求体结构
{
 "name": "a.png",
 "data": "<base64>",
 "mime": "image/png"
}
返回示例 / 结构
{"ok":true,"kind":"image","url":"…"}
POSThttps://snowfure.com/api/chat/asrasr_transcribe
语音转文字 · 参数：data, mime
curl 示例
curl -s -X POST 'https://snowfure.com/api/chat/asr?key=$KEY' -H 'Content-Type: application/json' -d '{"data": "<base64 音频>", "mime": "audio/wav"}'
请求体结构
{
 "data": "<base64 音频>",
 "mime": "audio/wav"
}
返回示例 / 结构
{"ok":true,"text":"…"}

IM · 消息/任务/群/机器人插件im · 15 个接口

IM 插件（机器人）接入走 WebSocket 协议，完整说明见 https://snowfure.com/im-plugin-spec.md
GEThttps://snowfure.com/api/im/convoslist_im_tasks
查 · 列曾健的任务（带编号 T1/T2…、进行中/已完成状态） · 参数：kind（固定 group，不用传）
curl 示例
curl -s 'https://snowfure.com/api/im/convos?key=$KEY&kind（固定=…'
POSThttps://snowfure.com/api/im/convo/donecomplete_task
改 · 把任务标记为已完成（task 传编号如 T3，或会话 id） · 参数：task, done=1
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/im/convo/donereopen_task
改 · 重新打开已完成的任务（task 传编号如 T3，或会话 id） · 参数：task, done=0
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/im/messagesread_im_task
查 · 读一个任务里的消息记录（谁说了什么） · 参数：conv, before?
curl 示例
curl -s 'https://snowfure.com/api/im/messages?key=$KEY&conv=…'
POSThttps://snowfure.com/api/im/sendsend_im_task
增 · 往任务里发一条消息（@ 谁谁回） · 参数：conv, text
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/im/convo/renamerename_im_task
改 · 重命名任务 · 参数：id, title
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/convo/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/im/convo/deletedelete_im_task
删 · 删除任务 · 参数：id
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/convo/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/im/convosim_list_convos
IM 会话列表
curl 示例
curl -s 'https://snowfure.com/api/im/convos?key=$KEY'
POSThttps://snowfure.com/api/im/sendim_send
发 IM 消息 · 参数：conv, text
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{"conv": "<会话 id>", "text": "你好"}'
请求体结构
{
 "conv": "<会话 id>",
 "text": "你好"
}
返回示例 / 结构
{"ok":true,"seq":123}
GEThttps://snowfure.com/api/im/peopleim_people
IM 成员
curl 示例
curl -s 'https://snowfure.com/api/im/people?key=$KEY'
GEThttps://snowfure.com/api/im/contactsim_contacts
IM 通讯录（人+智能体）
curl 示例
curl -s 'https://snowfure.com/api/im/contacts?key=$KEY'
GEThttps://snowfure.com/api/im/pluginsim_plugins
IM 插件注册表+在线状态
curl 示例
curl -s 'https://snowfure.com/api/im/plugins?key=$KEY'
POSThttps://snowfure.com/api/im/plugins/testim_plugin_test
测试插件连通 · 参数：id
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/plugins/test?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/im/ws/endpointim_ws_endpoint
取 IM 长连接地址 + ClientConfig（仿飞书） · 参数：app_id, app_secret
curl 示例
curl -s -X POST 'https://snowfure.com/api/im/ws/endpoint?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/im/ws/statusim_ws_status
IM 长连接在线状态（排查用）
curl 示例
curl -s 'https://snowfure.com/api/im/ws/status?key=$KEY'

文档 · 知识库/草稿docs · 8 个接口

GEThttps://snowfure.com/api/kb/web_searchweb_search
查 · 联网搜索（Bing）拿标题/网址/摘要 · 参数：q, n?
curl 示例
curl -s 'https://snowfure.com/api/kb/web_search?key=$KEY&q=…'
POSThttps://snowfure.com/api/kb/import_urlimport_url
改 · 抓网页正文入库（自动跑流水线+图谱） · 参数：url, title?
curl 示例
curl -s -X POST 'https://snowfure.com/api/kb/import_url?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/kb/web_pipelineweb_pipeline
改 · 联网搜索并抓前 N 篇自动入库（知识采集一条龙） · 参数：q, n?
curl 示例
curl -s -X POST 'https://snowfure.com/api/kb/web_pipeline?key=$KEY' -H 'Content-Type: application/json' -d '{}'
GEThttps://snowfure.com/api/kb/searchkb_search
查 · 知识库检索（上传入库的 PDF / Word / 表格 / 网页内容） · 参数：q, limit?
curl 示例
curl -s 'https://snowfure.com/api/kb/search?key=$KEY&q=…'
GEThttps://snowfure.com/api/kb/docskb_list
查 · 知识库文档清单
curl 示例
curl -s 'https://snowfure.com/api/kb/docs?key=$KEY'
GEThttps://snowfure.com/api/v1/appslist_apps
IM 应用清单（app_id，不含密钥）
curl 示例
curl -s 'https://snowfure.com/api/v1/apps?key=$KEY'
POSThttps://snowfure.com/api/v1/appscreate_app
注册 IM 应用 → app_id/app_secret（harness 插件接入用） · 参数：name, ident, engine, glyph
curl 示例
curl -s -X POST 'https://snowfure.com/api/v1/apps?key=$KEY' -H 'Content-Type: application/json' -d '{}'
POSThttps://snowfure.com/api/v1/auth/app_access_token/internalapp_access_token
应用换 token（仿飞书，2h 有效） · 参数：app_id, app_secret
curl 示例
curl -s -X POST 'https://snowfure.com/api/v1/auth/app_access_token/internal?key=$KEY' -H 'Content-Type: application/json' -d '{}'

管理 · 密钥/用户/统计admin · 1 个接口

GEThttps://snowfure.com/api/v1/keyslist_api_keys
API 密钥清单
curl 示例
curl -s 'https://snowfure.com/api/v1/keys?key=$KEY'