Logo

API 文档

欢迎使用 Clipzy API。此 API 允许您以编程方式创建和检索端到端加密的文本片段。

基本信息

  • 基础 URL: 相对于当前域名。
  • 认证: 无需认证，安全性依赖链接片段中的密钥。
  • 数据格式: 请求和响应均为 JSON (application/json)。
  • 数据留存与大小限制:
    • 默认 1 小时 (ttl=3600) 后删除。
    • 可通过 ttl 参数自定义：
      • 正数：指定留存秒数（服务器端最大限制约 30 天）。
      • -1：永久存储（无过期时间）。
    • 大小限制:
      • 永久或超过 7 天：约 17 万字符上限。
      • 7 天及以内：约 200 万字符上限。
      • (注意：服务器端基于压缩后数据有对应限制，分别为 ~0.6MB 和 ~8MB)
  • 加密: 客户端 AES-GCM 加密，密钥仅在 URL 片段中。

端点

创建加密片段

POST/api/store

上传压缩后加密的数据，返回唯一 ID。

请求 Body

{
  "compressedData": "string", // 必需：加密并 LZString 压缩后的 Base64 字符串
  "ttl": number | null       // 可选：秒。正数秒数 (最大约30天), -1 为永久, 默认 3600
}

响应 (200 OK)

{
  "id": "string" // 用于构建分享链接的唯一 ID
}

错误响应

  • 400 Bad Request: 请求体缺失或格式错误。
  • 413 Payload Too Large: 请求体（压缩后数据）超过限制。
    • 若 TTL 为永久或 > 7天: 限制约 0.6MB。
    • 若 TTL <= 7天: 限制为 8MB。
  • 405 Method Not Allowed: 非 POST 方法。
  • 500 Internal Server Error: 服务器错误。
{
  "error": "string",    // 错误信息
  "details"?: "string" // 可选：详细说明
}

获取加密片段

GET/api/get

根据 ID 获取加密并压缩的数据。

查询参数

  • id=string (必需)：片段唯一 ID。

示例：/api/get?id=your_unique_id

响应 (200 OK)

{
  "compressedData": "string" // 加密并压缩后的数据
}

错误响应

  • 400 Bad Request: 缺少或无效 ID。
  • 404 Not Found: 片段不存在或已过期。
  • 405 Method Not Allowed: 非 GET 方法。
  • 500 Internal Server Error: 服务器错误。
{
  "error": "string",    // 错误信息
  "details"?: "string" // 可选：详细说明
}

获取原始文本 (服务器端解密)

GET/api/raw/{id}

根据 ID 和密钥获取解密后的原始文本内容。数据在服务器端解密后直接以 text/plain 格式返回。

路径参数

  • {id} (必需)：片段唯一 ID。

查询参数

  • key=string (必需)：用于解密的 Base64 编码的 AES 密钥。

示例：/api/raw/your_unique_id?key=your_base64_key

响应 (200 OK)

Content-Type: text/plain; charset=utf-8

解密后的纯文本内容...

错误响应

  • 400 Bad Request: 缺少或无效的 ID 或密钥。
  • 403 Forbidden: 提供的密钥无法解密数据。
  • 404 Not Found: 片段不存在或已过期。
  • 405 Method Not Allowed: 非 GET 方法。
  • 500 Internal Server Error: 服务器错误（例如解密失败）。
{
  "error": "string",    // 错误信息
  "details"?: "string" // 可选：详细说明
}

客户端工作流程

前端与 API 交互流程：

  1. 生成 AES-GCM 密钥 (generateKey)。
  2. 加密文本 (encryptData)。
  3. 压缩密文 (compressString)。
  4. POST /api/store 上传数据并可选设置 ttl。
  5. 组合 URL，例如 https://domain/#id!base64Key。
  6. 分享该 URL。
  7. 访问时解析 URL 片段获取 ID 和密钥。
  8. GET /api/get?id=ID 获取数据。
  9. 解压 (decompressString)。
  10. 解密 (decryptData) 并显示文本。

密钥仅在客户端保留，确保端到端加密安全。