我的编程学习记录 学习笔记与实验归档

REST API

上报接口

仅提供 POST /api/conversations/ 用于客户端上报对话记录。数据查看与管理操作请在控制台登录后进行，不通过 API 暴露。

鉴权

上报接口接受 JSON 请求体（Content-Type: application/json）。

调用方 方法 凭证
客户端上报 POST 当前未启用上传凭证。生产环境建议配置 CONVERSATION_UPLOAD_TOKEN

单次请求体不超过 2097152 字节；同一 IP 每小时最多上报 60 次。

POST /api/conversations/

创建一条采集记录。conversation 必须是对话 JSON 文本的 Base64。服务端解码为 UTF-8 文本、校验 JSON，并保存为文件。成功返回 201。

Request body

字段类型必填说明
conversationstring (Base64)是将对话 JSON 序列化为 UTF-8 文本后再做 Base64。解码后须为对象或数组
conversation_idstring否客户端侧对话 ID
titlestring否标题；缺省时按首条用户消息生成
feedbackstring否用户反馈
ratinginteger否1–5
tagsarray / string否标签数组，或逗号分隔字符串
userobject否id、name、email、extra
clientobject否app_version、os、device

Response 201

{
  "ok": true,
  "id": "ef9a1071-b810-48bc-ab30-c6b8b59c8b5c",
  "title": "帮我总结这次会议",
  "message_count": 2,
  "created_at": "2026-08-28T15:00:48.657940+00:00"
}

错误码

HTTP含义示例
400请求体不合法缺少 Base64 对话、解码失败，或评分不在 1–5
401未授权上传凭证错误
405方法不允许使用 GET / PATCH 等非 POST 方法
429频率限制同一 IP 上报过于频繁
 
{
  "ok": false,
  "error": "缺少 conversation 字段"
}

调用示例

curl 上报

# conversation 为对话 JSON 的 Base64
curl -X POST https://kekehui.top/api/conversations/ \
  -H "Content-Type: application/json" \
  -d "{
    \"conversation\": \"eyJyb2xlIjoidXNlciJ9\",
    \"feedback\": \"结构完整，细节不足\",
    \"rating\": 4,
    \"user\": {\"id\": \"u_1001\", \"name\": \"analyst\"},
    \"client\": {\"app_version\": \"1.2.0\", \"os\": \"Windows 10\"}
  }"

Python 上报

import base64
import json
import urllib.request

messages = [
    {"role": "user", "content": "帮我写一份周报"},
    {"role": "assistant", "content": "好的，这是提纲。"},
]
conversation = base64.b64encode(
    json.dumps(messages, ensure_ascii=False).encode("utf-8")
).decode("ascii")

payload = {
    "conversation": conversation,
    "feedback": "未按给定格式输出",
    "rating": 2,
    "user": {"id": "u_123", "name": "analyst"},
    "client": {"app_version": "1.0.0", "os": "Windows 10"},
}

req = urllib.request.Request(
    "https://kekehui.top/api/conversations/",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode("utf-8"))