metadata

title: Notion API 轻量级客户端
emoji: 📝
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860

Notion API 轻量级客户端 (Hugging Face Space)

这个项目提供了一个轻量级的 Notion API 客户端，可以作为 Web 服务部署在 Hugging Face Spaces 上。它兼容 OpenAI API 格式，让你可以将 Notion AI 作为后端集成到各种应用中。

🚀 在 Hugging Face Spaces 上部署

创建 Space: 在 Hugging Face 上创建一个新的 Space。
选择 Docker SDK: 在 "Choose an SDK" 步骤中，选择 "Docker"。
上传文件: 将此项目的所有文件（包括 Dockerfile）上传到你的 Space Git 仓库中。
设置 Secrets: 这是最重要的一步。你的 Notion 凭证和其他配置需要作为 Secrets 添加到 Space 中。进入你的 Space "Settings" 页面，找到 "Repository secrets" 部分，然后点击 "New secret" 添加以下变量：
- 必需:
  - NOTION_COOKIE: 你的 Notion Cookie。你可以通过浏览器开发者工具获取。
- 可选:
  - NOTION_SPACE_ID: 你的 Notion Space ID。
  - NOTION_ACTIVE_USER_HEADER: 你的 Notion 用户 ID。
  - PROXY_URL: 如果你需要通过代理访问 Notion，请设置此项 (例如 http://user:pass@host:port)。
  - PROXY_AUTH_TOKEN: 如果你的代理需要单独的认证令牌，请设置此项。
  - COOKIE_FILE: 如果你使用文件管理多个 Cookie，请设置为文件名 (例如 cookies.txt)。请确保该文件也已上传到仓库中。
注意: PORT 环境变量由 Hugging Face 自动处理，你无需设置。
等待部署: 添加完 Secrets 后，Hugging Face 会自动构建 Docker 镜像并部署你的应用。你可以在 "Logs" 标签页查看部署进度和应用日志。部署成功后，你的 API 端点即可使用。

📖 API 使用说明

服务启动后，你可以通过你的 Space URL 访问 API。

基础 URL: https://<your-space-name>.hf.space

API 端点

GET /v1/models - 获取可用模型列表 (主要是为了兼容 OpenAI 客户端)
POST /v1/chat/completions - 核心的聊天完成端点
GET /health - 健康检查端点

示例: 使用 cURL 调用

curl -X POST https://<your-space-name>.hf.space/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
    "model": "openai-gpt-4.1",
    "messages": [
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "stream": true
}'

请将 <your-space-name> 替换为你的 Space 名称。

🍪 Cookie 管理

为了提高服务的稳定性，你可以提供多个 Notion Cookie。

通过文件管理 Cookie

在项目根目录创建一个 cookies.txt 或 cookies.json 文件。
将文件上传到你的 Space 仓库。
在 Space Secrets 中设置 COOKIE_FILE 为你的文件名 (例如 cookies.txt)。

系统启动时会自动从该文件加载Cookie。

cookies.txt 示例: (每行一个Cookie)

cookie1_string_here
cookie2_string_here

cookies.json 示例:

{
  "cookies": [
    "cookie1_string_here",
    "cookie2_string_here"
  ]
}

Cookie 轮询机制

系统会自动轮询使用所有有效的Cookie。当一个Cookie失效时（例如返回401错误），会自动切换到下一个有效的Cookie，确保服务不中断。

本地开发参考

以下信息用于在本地计算机上运行和开发。

依赖项

npm install

环境变量

创建 .env 文件，设置以下环境变量：

NOTION_COOKIE=your_notion_cookie_here
NOTION_SPACE_ID=optional_space_id
NOTION_ACTIVE_USER_HEADER=optional_user_id
PROXY_URL=optional_proxy_url
PROXY_AUTH_TOKEN=your_auth_token
PORT=7860

启动服务

npm start

Cookie 管理命令行工具

项目提供了一个命令行工具来方便地管理 cookies.json 文件。

# 运行命令行工具
npm run cookie

# 支持的命令
help, list, add, validate, remove, save, load, exit