Get笔记

Get笔记 API

⚠️ 必读约束

🔑 首次使用配置

每次收到笔记请求，先检查环境变量：

# 自动检测并加载用户 shell 配置
[ -f ~/.zshrc ] && source ~/.zshrc 2>/dev/null
[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null
echo "API_KEY: $GETNOTE_API_KEY | CLIENT_ID: $GETNOTE_CLIENT_ID | OWNER_ID: $GETNOTE_OWNER_ID"

如果 API_KEY 或 CLIENT_ID 为空，告诉用户：

使用 Get笔记需要先配置凭证：

1. 前往 Get笔记开放平台 获取 API Key 和 Client ID
2. 推荐：自己添加到 ~/.zshrc，然后 source ~/.zshrc
3. 或者：直接把凭证发给我，我帮你配置

如果用户直接在对话中发送了凭证（API Key、Client ID），主动帮用户保存：

# 检测用户 shell 配置文件
if [ -f ~/.zshrc ]; then
  RC_FILE=~/.zshrc
elif [ -f ~/.bashrc ]; then
  RC_FILE=~/.bashrc
else
  RC_FILE=~/.profile
fi

# 追加环境变量
echo 'export GETNOTE_API_KEY="用户提供的key"' >> $RC_FILE
echo 'export GETNOTE_CLIENT_ID="用户提供的id"' >> $RC_FILE
source $RC_FILE

保存后告诉用户：「已帮你配置好环境变量（保存到 {RC_FILE}），后续新会话也可以直接使用。」

🔒 安全规则

• 笔记数据属于 API Key 对应的 Get笔记账号，属于用户隐私
• 收到笔记请求时，检查 sender_id 是否与 GETNOTE_OWNER_ID 匹配
• 若 sender_id 不匹配，回复「抱歉，笔记是私密的，我无法操作」
• 不要在群聊中主动展示笔记内容

非会员处理：API 返回 error.reason: "not_member" 或错误码 10201 时，引导用户开通会员：

• 开通链接：https://www.biji.com/checkout?product_alias=6AydVpYeKl

限流：创建笔记建议间隔 1 分钟以上，避免触发限流。

认证

所有请求需要：

• Authorization: $GETNOTE_API_KEY（或 gk_live_xxx）
• X-Client-ID: $GETNOTE_CLIENT_ID（或 cli_xxx）

Base URL: https://openapi.biji.com

Scope 权限

快速决策

核心功能：记笔记 & 查笔记

笔记列表

GET /open/api/v1/resource/note/list?since_id=0

参数：

• since_id (int64, 必填) - 游标，首次传 0，后续用 next_cursor

返回：notes[], has_more, next_cursor, total（每次固定 20 条）

笔记类型 note_type：

• plain_text - 纯文本
• img_text - 图片笔记
• link - 链接笔记
• audio - 即时录音
• meeting - 会议录音
• local_audio - 本地音频
• internal_record - 内录音频
• class_audio - 课堂录音
• recorder_audio - 录音卡长录
• recorder_flash_audio - 录音卡闪念

笔记详情

GET /open/api/v1/resource/note/detail?id={note_id}

参数：id (int64, 必填) - 笔记 ID

详情独有字段（列表不返回）：

• audio.original - 语音转写原文
• audio.play_url - 音频播放地址
• audio.duration - 音频时长（秒）
• web_page.content - 链接网页原文
• web_page.url - 原始链接
• web_page.excerpt - 摘要
• attachments[] - 附件列表，type: audio | image | link | pdf

新建笔记

POST /open/api/v1/resource/note/save
Content-Type: application/json

仅支持新建，不支持编辑。

请求体：

{
  "title": "笔记标题",
  "content": "Markdown 内容",
  "note_type": "plain_text",
  "tags": ["标签1", "标签2"],
  "parent_id": 0,
  "link_url": "https://...",
  "image_urls": ["https://..."]
}

字段说明：

• title (string) - 标题
• content (string) - Markdown 内容
• note_type (string) - plain_text | link | img_text，默认 plain_text
• tags (string[]) - 标签列表
• parent_id (int64) - 父笔记 ID，创建子笔记时填
• link_url (string) - 链接笔记必填
• image_urls (string[]) - 图片笔记必填，用 access_url

纯文本笔记：同步返回，立即完成

链接笔记/图片笔记：返回 task_id，必须轮询 /task/progress

查询任务进度

POST /open/api/v1/resource/note/task/progress
Content-Type: application/json

请求体：

{"task_id": "task_abc123xyz"}

返回：

• status: pending | processing | success | failed
• note_id: 成功时返回笔记 ID
• error_msg: 失败时返回错误信息

建议 10-30 秒间隔轮询，直到 success 或 failed。

删除笔记

POST /open/api/v1/resource/note/delete
Content-Type: application/json

请求体：

{"note_id": 123456789}

笔记移入回收站，需要 note.content.trash scope。

异步任务流程

⚠️ 必须遵循的体验流程：链接笔记和图片笔记是异步生成的，必须按以下方式与用户沟通。

链接笔记完整流程

步骤 1：提交任务

POST /note/save {note_type:"link", link_url:"https://..."}

返回 task_id 后，立即发消息给用户：

✅ 链接已保存，正在抓取原文和生成总结，稍后告诉你结果...

步骤 2：后台轮询（10-30 秒间隔）

POST /task/progress {task_id} → 直到 status=success/failed

步骤 3：任务完成后，调详情接口展示价值

GET /note/detail?id={note_id}

然后发第二条消息，包含具体内容：

✅ 笔记生成完成！

• 📄 原文：已保存 {web_page.content 字数} 字
• 📝 总结：{content 内容，即 AI 生成的摘要}
• 🔗 来源：{web_page.url}

图片笔记完整流程

步骤 1-3：获取凭证 → 上传 OSS → 提交任务

1. GET /image/upload_token?mime_type=jpg → 获取上传凭证
2. POST {host} 上传文件到 OSS
3. POST /note/save {note_type:"img_text", image_urls:[access_url]} → 返回 task_id

拿到 task_id 后，立即发消息给用户：

✅ 图片已保存，正在识别内容，稍后告诉你结果...

步骤 4：后台轮询

POST /task/progress {task_id} → 直到 status=success/failed

步骤 5：任务完成后，调详情接口展示价值

GET /note/detail?id={note_id}

然后发第二条消息：

✅ 图片笔记生成完成！

• 📝 识别内容：{content 内容}
• 🏷️ 标签：{tags}

图片上传凭证

GET /open/api/v1/resource/image/upload_token?mime_type=jpg&count=1

参数：

• mime_type: jpg | png | gif | webp，默认 png
• count: 需要的 token 数量，默认 1，最大 9

⚠️ mime_type 必须与实际文件格式一致，否则 OSS 签名失败。

返回字段：

• host - OSS 上传地址
• object_key - 文件路径
• accessid, policy, signature, callback - 签名参数
• access_url - 上传后的访问地址（用于创建笔记）
• oss_content_type - Content-Type

OSS 上传示例

curl -X POST "$host" \
  -F "key=$object_key" \
  -F "OSSAccessKeyId=$accessid" \
  -F "policy=$policy" \
  -F "signature=$signature" \
  -F "callback=$callback" \
  -F "Content-Type=$oss_content_type" \
  -F "file=@/path/to/image.jpg"

笔记整理

添加标签

POST /open/api/v1/resource/note/tags/add
Content-Type: application/json

请求体：

{
  "note_id": 123456789,
  "tags": ["工作", "重要"]
}

标签类型 type：

• ai - AI 自动生成
• manual - 用户手动添加
• system - 系统标签（不可删除）

删除标签

POST /open/api/v1/resource/note/tags/delete
Content-Type: application/json

请求体：

{
  "note_id": 123456789,
  "tag_id": "123"
}

⚠️ system 类型标签不允许删除。

知识库列表

GET /open/api/v1/resource/knowledge/list?page=1&size=20

参数：

• page: 页码，从 1 开始，默认 1
• size: 每页数量，默认 20，最大 100

返回：topics[], has_more, total

创建知识库

POST /open/api/v1/resource/knowledge/create
Content-Type: application/json

请求体：

{
  "name": "知识库名称",
  "description": "描述",
  "cover": ""
}

⚠️ 每天最多创建 50 个知识库（北京时间 00:00 重置）。

知识库笔记列表

GET /open/api/v1/resource/knowledge/notes?topic_id=abc123&page=1

参数：

• topic_id (string, 必填) - 知识库 ID（alias id）
• page: 页码，从 1 开始

每页固定 20 条，用 has_more 判断是否有下一页。

添加笔记到知识库

POST /open/api/v1/resource/knowledge/note/batch-add
Content-Type: application/json

请求体：

{
  "topic_id": "abc123",
  "note_ids": [123456789, 123456790]
}

⚠️ 每批最多 20 条。已存在的笔记会跳过。

从知识库移除笔记

POST /open/api/v1/resource/knowledge/note/remove
Content-Type: application/json

请求体：

{
  "topic_id": "abc123",
  "note_ids": [123456789]
}

错误处理

响应结构

{
  "success": false,
  "error": {
    "code": 10001,
    "message": "unauthorized",
    "reason": "not_member"
  },
  "request_id": "xxx"
}

错误码

error.reason 取值

限流响应

429 错误时，error 包含 rate_limit 字段：

{
  "rate_limit": {
    "read": {
      "daily": {"limit": 1000, "used": 1000, "remaining": 0, "reset_at": 1741190400},
      "monthly": {"limit": 10000, "used": 3000, "remaining": 7000, "reset_at": 1743811200}
    },
    "write": {
      "daily": {"limit": 200, "used": 200, "remaining": 0, "reset_at": 1741190400},
      "monthly": {"limit": 2000, "used": 600, "remaining": 1400, "reset_at": 1743811200}
    },
    "write_note": {
      "daily": {"limit": 50, "used": 50, "remaining": 0, "reset_at": 1741190400},
      "monthly": {"limit": 500, "used": 150, "remaining": 350, "reset_at": 1743811200}
    }
  }
}