> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 概览

> Profy App SDK 帮助开发者快速对接 OAuth 授权、计费上报和 AI 模型调用，专注于构建 App 业务逻辑。

# Profy App SDK

一行代码接入 Profy 平台的 OAuth 授权与计费能力，让你的 App 专注业务逻辑。

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @profy-ai/sdk
  ```

  ```bash Python theme={null}
  pip install profy-sdk
  ```
</CodeGroup>

## 你可以用 SDK 构建什么

<CardGroup cols={2}>
  <Card title="SaaS 按次计费" icon="receipt">
    用户在你的 App 中触发付费操作（生成报告、导出文件），SDK 自动扣费并处理余额不足提示。
  </Card>

  <Card title="AI 工具封装" icon="wand-magic-sparkles">
    调用 Profy 平台的 AI 模型（OpenAI 兼容接口），用户按 token 用量付费，你无需管理 API Key。
  </Card>

  <Card title="Expert 集成" icon="robot">
    在你的 App 中调用平台上已发布的 AI Expert，获取 SSE 流式回复，按 token 计费。
  </Card>

  <Card title="多租户鉴权" icon="users">
    OAuth 2.0 标准流程，SDK 自动管理 Token 生命周期（签发、刷新、轮换），支持 Drizzle / SQLAlchemy 持久化。
  </Card>
</CardGroup>

## 核心能力

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

## 两种计费模型

<CardGroup cols={2}>
  <Card title="PER_USE — 按次计费" icon="coins">
    App 定义自定义事件（如 `generate_report`），每次调用固定扣费。适合明确的单次操作。

    ```typescript theme={null}
    await profy.reportEvent("generate_report", { token });
    ```
  </Card>

  <Card title="METERED — 按量计费" icon="gauge-high">
    调用 AI 模型或 Expert，按实际 token 消耗扣费。适合对话、生成等不定量场景。

    ```typescript theme={null}
    await fetch(baseUrl + "/openapi/v1/events/chat", {
      headers: { Authorization: `Bearer ${token.accessToken}` },
      body: JSON.stringify({ model: "deepseek-v3", messages }),
    });
    ```
  </Card>
</CardGroup>

## 架构

```mermaid theme={null}
graph LR
    A[你的 App] -->|SDK 封装| B[Profy SDK]
    B -->|OAuth 2.0| C[Profy 授权服务]
    B -->|Events API| D[Profy 计费网关]
    D --> E[用户积分扣减]
    D --> F[创作者收益结算]
    C --> G[Token 签发 / 刷新]
```

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

## 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 自动重试            | 自己实现                         |

<Tip>
  两种方式完全等价。SDK 不引入额外的平台绑定，底层就是标准 HTTP 调用。
</Tip>

## 开始使用

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/zh/sdk/quickstart">
    5 分钟完成安装、OAuth 对接和首次事件上报
  </Card>

  <Card title="完整 SDK 指南" icon="book" href="/zh/documentation/sdk-guide">
    双语言 API 详解、Token 持久化方案与最佳实践
  </Card>

  <Card title="API 参考" icon="code" href="/zh/api/post-token">
    OAuth 端点与 Events API 完整字段说明
  </Card>

  <Card title="应用接入教程" icon="puzzle-piece" href="/zh/documentation/integration-quickstart">
    从零创建 App、配置 OAuth、上架市场的完整流程
  </Card>
</CardGroup>