跳转到主要内容

​
Profy App SDK

一行代码接入 Profy 平台的 OAuth 授权与计费能力，让你的 App 专注业务逻辑。 
npm install @profy-ai/sdk

pip install profy-sdk

​
你可以用 SDK 构建什么

SaaS 按次计费

用户在你的 App 中触发付费操作（生成报告、导出文件），SDK 自动扣费并处理余额不足提示。

AI 工具封装

调用 Profy 平台的 AI 模型（OpenAI 兼容接口），用户按 token 用量付费，你无需管理 API Key。

Expert 集成

在你的 App 中调用平台上已发布的 AI Expert，获取 SSE 流式回复，按 token 计费。

多租户鉴权

OAuth 2.0 标准流程，SDK 自动管理 Token 生命周期（签发、刷新、轮换），支持 Drizzle / SQLAlchemy 持久化。

​
核心能力

能力方法 / 端点说明
OAuth 授权码交换exchangeCode()将回调 code 换成 Access + Refresh Token
Token 自动刷新refreshToken()Access Token 过期时自动续期，业务层无感
自定义计费事件reportEvent() → POST /openapi/v1/eventsPER_USE 模型，固定价格按次扣费
AI 模型调用POST /openapi/v1/events/chatMETERED 模型，OpenAI 兼容，按 token 计费
Expert 调用POST /openapi/v1/events/invokeMETERED 模型，SSE 流式响应
Token 持久化Contrib: Drizzle / SQLAlchemy可选存储层，也可自定义
结构化错误AuthExpired / InsufficientBalance / InvalidEvent / ProfyApiError精确匹配异常类型，业务侧分支处理

​
两种计费模型

PER_USE — 按次计费

App 定义自定义事件（如 generate_report），每次调用固定扣费。适合明确的单次操作。
await profy.reportEvent("generate_report", { token });

METERED — 按量计费

调用 AI 模型或 Expert，按实际 token 消耗扣费。适合对话、生成等不定量场景。
await fetch(baseUrl + "/openapi/v1/events/chat", {
  headers: { Authorization: `Bearer ${token.accessToken}` },
  body: JSON.stringify({ model: "deepseek-v3", messages }),
});

​
架构

SDK 只是对 HTTP API 的薄封装。你也可以直接调用 REST 端点实现相同效果——SDK 的价值在于自动 Token 刷新和结构化错误处理。

​
SDK vs 自建

维度用 SDK自建 HTTP 调用
Token 交换profy.exchangeCode()手动 POST /oauth/token
Token 刷新自动检测过期 + 无感续期自己实现过期检测 + retry
计费上报profy.reportEvent()手动 POST /openapi/v1/events
AI 调用OpenAI 兼容 + SDK 鉴权自己拼 Header + 处理流式
存储Contrib 模块一行接入完全自建表结构
错误处理结构化异常类自己解析 HTTP status + body
幂等重试内置 401 自动重试自己实现
两种方式完全等价。SDK 不引入额外的平台绑定，底层就是标准 HTTP 调用。

​
开始使用

快速开始

5 分钟完成安装、OAuth 对接和首次事件上报

完整 SDK 指南

双语言 API 详解、Token 持久化方案与最佳实践

API 参考

OAuth 端点与 Events API 完整字段说明

应用接入教程

从零创建 App、配置 OAuth、上架市场的完整流程