API 使用文档

快速上手 Rnote API，从注册到发起第一个请求

开始之前

1. 1 注册账户 并完成邮箱验证
2. 2 登录 管理后台，在「API Key 管理」中创建一个 API Key
3. 3 在「计费」页面充值余额（仅成功请求扣费）

认证方式

所有 API 请求需要通过 X-API-Key Header 传递 API Key 进行认证。

# 在 HTTP Header 中传递 API Key
curl -X 'GET' \
  'https://rnote.dev/api/v2/crawler/note/image?note_id=697c0eee000000000a03c308' \
  -H 'accept: application/json' \
  -H 'X-API-Key: sk-5bc4****************************e175'

第一个请求

以获取图文笔记详情为例：

curl -X 'GET' \
  'https://rnote.dev/api/v2/crawler/note/image?note_id=697c0eee000000000a03c308' \
  -H 'accept: application/json' \
  -H 'X-API-Key: sk-5bc4****************************e175'

import requests

API_KEY = "sk-5bc4****************************e175"
BASE_URL = "https://rnote.dev/api/v2/crawler"

response = requests.get(
    f"{BASE_URL}/note/image",
    params={"note_id": "697c0eee000000000a03c308"},
    headers={
        "X-API-Key": API_KEY,
        "accept": "application/json",
    },
)

data = response.json()
print(data)

const API_KEY = "sk-5bc4****************************e175";
const BASE_URL = "https://rnote.dev/api/v2/crawler";

const res = await fetch(
  `${BASE_URL}/note/image?note_id=697c0eee000000000a03c308`,
  {
    headers: {
      "X-API-Key": API_KEY,
      "accept": "application/json",
    },
  }
);

const data = await res.json();
console.log(data);

笔记接口

用户接口

搜索接口

商品接口

话题接口

创作灵感

响应格式

所有 V2 爬虫接口（/api/v2/crawler/*）使用统一的 JSON 响应结构：

成功响应

{
  "success": true,
  "data": { /* 业务数据，结构因接口而异 */ },
  "billed": true,
  "debug_id": "a1b2c3d4",
  "debug_info": "gAAAAABm... (Fernet 密文，仅管理员可解)"
}

失败响应

{
  "success": false,
  "data": null,
  "error": "请求过于频繁，请稍后重试",
  "retry_after": 5.0,
  "billed": false,
  "debug_id": "a1b2c3d4",
  "debug_info": "gAAAAABm... (Fernet 密文，仅管理员可解)"
}

字段说明

错误码

中间件层（鉴权 / 限流 / 计费）

这些状态码在请求到达业务逻辑前就会返回，与具体接口无关。

业务接口层（V2 爬虫）

V2 爬虫接口失败响应使用标准 4xx/5xx 状态码 + Retry-After 头。请同时检查 HTTP 状态码和 body.success。

客户端错误处理示例

推荐写法 —— 同时检查 HTTP 状态码和 body.success，并在异常日志里附上 debug_id：

import requests

resp = requests.get(
    "https://rnote.dev/api/v2/crawler/user/info",
    headers={"X-API-Key": "sk-..."},
    params={"user_id": "..."},
    timeout=20,
)
body = resp.json()

# 双重判断: HTTP status 优先, body.success 兜底
if resp.status_code >= 400 or not body.get("success"):
    error = body.get("error", "未知错误")
    debug_id = body.get("debug_id", "n/a")
    retry_after = body.get("retry_after")
    print(f"请求失败 [{debug_id}]: {error}", end="")
    if retry_after:
        print(f" (建议 {retry_after}s 后重试)")
    # 联系支持时附上 debug_id 或完整 debug_info
else:
    data = body["data"]
    # 处理业务数据 ...

计费说明