237899745/ystp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ystp/docs/api.md

15 KiB
Raw Permalink Blame History

API 接口文档（v1）- ImageForge

面向两类使用者：

  • 网站（Web）：上传/批量/历史/账单等（可能包含匿名试用）。
  • 对外 API（Developer API）：API Key 调用、可计量可计费、适配 CI/CD 与服务端集成。

产品范围与计费口径见：

  • docs/prd.md
  • docs/billing.md

1. 基础信息

  • Base URL: https://your-domain.com/api/v1
  • 数据格式: JSON（除明确标注“返回二进制”接口）
  • 时间格式: ISO 8601 / UTC（如：2025-01-15T10:30:00Z）
  • ID 格式: UUID 字符串

2. 认证

支持三种身份：

2.1 JWT（网站/管理后台）

Authorization: Bearer <token>

2.2 API Key（对外 API）

X-API-Key: <your-api-key>

注意：仅 Pro 和 Business 套餐用户可创建 API Key。Free 用户尝试创建时返回 FORBIDDEN（HTTP 403）。

2.3 匿名试用（仅网站场景）

  • 不提供 API Key；
  • 通过 Cookie 维持匿名会话（服务端签发），仅允许较小文件与较低频率。
  • 每日 10 次（以成功压缩文件数计）；超出返回 QUOTA_EXCEEDED（HTTP 402）。
  • 日界：自然日（UTC+8），次日 00:00 重置。
  • 匿名试用硬限制：Cookie + IP 双限制（两者任一超出都拒绝），降低刷会话绕过风险。

3. 通用约定

3.1 幂等（强烈建议）

对会产生计费/创建任务的接口，建议客户端传：

Idempotency-Key: <uuid-or-random-string>

规则（建议口径）：

  • 同一个 Idempotency-Key 在 TTL 内重复请求，若请求参数一致则返回首次结果（不重复扣费/不重复创建任务）。
  • 若参数不一致，返回 409 IDEMPOTENCY_CONFLICT。

3.2 限流（Rate Limit）

超出限制返回：

  • HTTP 429
  • 头：Retry-After: <seconds>

建议头（可选）：

  • RateLimit-Limit
  • RateLimit-Remaining
  • RateLimit-Reset

3.3 配额（Quota / Billing）

配额不足（当期额度耗尽）返回：

  • HTTP 402
  • 错误码：QUOTA_EXCEEDED

配额周期：

  • Pro/Business（付费）：按订阅周期重置（period_start ~ period_end），不是自然月。
  • Free（未订阅）：按自然月（UTC+8）重置。
  • 匿名试用：按自然日（UTC+8）重置。

建议头（可选）：

  • X-Quota-Limit
  • X-Quota-Remaining
  • X-Quota-Reset-At

3.4 通用响应格式（JSON）

成功：

{ "success": true, "data": {} }

错误：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "request_id": "req_..."
  }
}

3.5 错误码（建议集合）

错误码 HTTP 说明
INVALID_REQUEST 400 参数不合法
INVALID_IMAGE 400 图片解码失败/文件损坏
UNSUPPORTED_FORMAT 400 不支持的格式
TOO_MANY_PIXELS 400 像素超限（防图片炸弹）
UNAUTHORIZED 401 未认证
FORBIDDEN 403 权限不足
NOT_FOUND 404 资源不存在
IDEMPOTENCY_CONFLICT 409 幂等 key 冲突
QUOTA_EXCEEDED 402 配额不足
FILE_TOO_LARGE 413 文件过大
RATE_LIMITED 429 请求过于频繁
EMAIL_NOT_VERIFIED 403 邮箱未验证
INVALID_TOKEN 400 Token 无效或已过期
COMPRESSION_FAILED 500 压缩失败
STORAGE_UNAVAILABLE 503 存储不可用
MAIL_SEND_FAILED 500 邮件发送失败

4. 认证接口

4.1 用户注册

POST /auth/register
Content-Type: application/json

请求体：

{ "email": "user@example.com", "password": "securepassword123", "username": "myusername" }

响应：

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "username": "myusername",
      "email_verified": false,
      "created_at": "2025-01-15T10:30:00Z"
    },
    "token": "eyJhbGciOi...",
    "message": "注册成功，验证邮件已发送至您的邮箱"
  }
}

注意：注册后自动发送验证邮件。用户需验证邮箱后才能使用压缩功能（未验证时调用压缩接口返回 EMAIL_NOT_VERIFIED）。

4.2 用户登录

POST /auth/login
Content-Type: application/json

请求体：

{ "email": "user@example.com", "password": "securepassword123" }

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "expires_at": "2025-01-22T10:30:00Z",
    "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "user@example.com", "username": "myusername", "role": "user" }
  }
}

4.3 刷新 Token

POST /auth/refresh
Authorization: Bearer <token>

4.4 登出

POST /auth/logout
Authorization: Bearer <token>

4.5 发送验证邮件

用户注册后自动发送一次；此接口用于重新发送。

POST /auth/send-verification
Authorization: Bearer <token>

限流：同一用户 1 分钟内最多 1 次

响应：

{ "success": true, "data": { "message": "验证邮件已发送，请查收" } }

4.6 验证邮箱

POST /auth/verify-email
Content-Type: application/json

请求体：

{ "token": "verification-token-from-email" }

响应：

{ "success": true, "data": { "message": "邮箱验证成功" } }

4.7 请求密码重置

POST /auth/forgot-password
Content-Type: application/json

请求体：

{ "email": "user@example.com" }

限流：同一 IP 1 分钟内最多 3 次

响应（无论邮箱是否存在都返回成功，防止枚举）：

{ "success": true, "data": { "message": "如果该邮箱已注册，您将收到重置邮件" } }

4.8 重置密码

POST /auth/reset-password
Content-Type: application/json

请求体：

{ "token": "reset-token-from-email", "new_password": "new-secure-password" }

响应：

{ "success": true, "data": { "message": "密码重置成功，请重新登录" } }

5. 图片压缩接口

5.1 单图压缩（同步，返回 JSON + 下载链接）

适用于网站与轻量同步调用（服务端可选择是否落盘/落对象存储）。

POST /compress
Content-Type: multipart/form-data
Authorization: Bearer <token>   # 或 X-API-Key；网站匿名试用可不带
Idempotency-Key: <key>          # 建议

表单字段：

字段 类型 必填 说明
file File 是 图片文件
compression_rate Integer 否 压缩率 1-100（压缩后体积占原图比例，数值越小压缩越强，100 表示不压缩），优先级高于 level
level String 否 high / medium / low（兼容参数，默认 medium）
output_format String 否 已停用，仅支持保持原格式
max_width Integer 否 最大宽度（等比缩放）
max_height Integer 否 最大高度（等比缩放）
preserve_metadata Boolean 否 是否保留元数据（默认 false）

响应：

{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440100",
    "file_id": "550e8400-e29b-41d4-a716-446655440101",
    "format_in": "png",
    "format_out": "png",
    "original_size": 1024000,
    "compressed_size": 256000,
    "saved_bytes": 768000,
    "saved_percent": 75.0,
    "download_url": "/downloads/550e8400-e29b-41d4-a716-446655440101",
    "expires_at": "2025-01-15T11:30:00Z",
    "billing": { "units_charged": 1 }
  }
}

5.2 单图压缩（同步，直接返回二进制）

更贴近开发者体验，适用于 SDK/CI。

POST /compress/direct
Content-Type: multipart/form-data
X-API-Key: <your-api-key>        # 或 Bearer token（不建议匿名）
Idempotency-Key: <key>           # 建议

成功响应：

  • HTTP 200
  • Body：压缩后的图片二进制
  • Content-Type: image/png / image/jpeg / image/webp / image/avif / image/gif / image/bmp / image/tiff / image/x-icon

建议响应头（示例）：

ImageForge-Original-Size: 1024000
ImageForge-Compressed-Size: 256000
ImageForge-Saved-Bytes: 768000
ImageForge-Saved-Percent: 75.0
ImageForge-Units-Charged: 1

5.3 批量压缩（异步任务）

适用于多文件或大文件；由 Worker 处理并持续更新进度。

POST /compress/batch
Content-Type: multipart/form-data
Authorization: Bearer <token>    # 或 X-API-Key
Idempotency-Key: <key>           # 建议

表单字段：

字段 类型 必填 说明
files[] File[] 是 图片文件数组（上限由套餐决定）
compression_rate Integer 否 压缩率 1-100（压缩后体积占原图比例，数值越小压缩越强，100 表示不压缩），优先级高于 level
level String 否 high / medium / low（兼容参数）
output_format String 否 已停用，仅支持保持原格式
preserve_metadata Boolean 否 是否保留元数据（默认 false）

响应：

{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440200",
    "total_files": 10,
    "status": "pending",
    "status_url": "/compress/tasks/550e8400-e29b-41d4-a716-446655440200"
  }
}

配额规则补充：

  • 若本周期剩余单位不足以覆盖本次上传的文件数，服务端应直接返回 402 QUOTA_EXCEEDED（不创建任务）。

5.4 查询任务状态

GET /compress/tasks/{task_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需携带 Cookie 会话

响应：

{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440200",
    "status": "completed",
    "progress": 100,
    "total_files": 10,
    "completed_files": 10,
    "failed_files": 0,
    "files": [
      {
        "file_id": "550e8400-e29b-41d4-a716-446655440201",
        "original_name": "photo1.png",
        "original_size": 1024000,
        "compressed_size": 256000,
        "saved_percent": 75.0,
        "status": "completed",
        "download_url": "/downloads/550e8400-e29b-41d4-a716-446655440201"
      }
    ],
    "download_all_url": "/downloads/tasks/550e8400-e29b-41d4-a716-446655440200",
    "created_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:31:00Z",
    "expires_at": "2025-01-22T10:30:00Z"
  }
}

5.5 取消任务（可选）

POST /compress/tasks/{task_id}/cancel
Authorization: Bearer <token>

5.6 删除任务与文件（隐私/合规）

DELETE /compress/tasks/{task_id}
Authorization: Bearer <token>

6. 下载接口

6.1 下载单个文件

GET /downloads/{file_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需 Cookie 会话

6.2 下载批量 ZIP

GET /downloads/tasks/{task_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需 Cookie 会话

7. 用户接口

7.1 获取当前用户信息

GET /user/profile
Authorization: Bearer <token>

响应（示例）：

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "myusername",
    "role": "user"
  }
}

7.2 更新用户信息

PUT /user/profile
Authorization: Bearer <token>
Content-Type: application/json

7.3 修改密码

PUT /user/password
Authorization: Bearer <token>
Content-Type: application/json

7.4 获取压缩历史

GET /user/history?page=1&limit=20
Authorization: Bearer <token>

8. API Key 管理

8.1 获取 API Key 列表

GET /user/api-keys
Authorization: Bearer <token>

8.2 创建 API Key

POST /user/api-keys
Authorization: Bearer <token>
Content-Type: application/json

请求体：

{ "name": "Production Server", "permissions": ["compress", "batch_compress"] }

响应：

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440300",
    "name": "Production Server",
    "key": "if_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "message": "请保存此 Key，它只会显示一次"
  }
}

8.3 轮换 API Key（可选）

POST /user/api-keys/{key_id}/rotate
Authorization: Bearer <token>

8.4 删除/禁用 API Key

DELETE /user/api-keys/{key_id}
Authorization: Bearer <token>

9. 计费与用量（Billing）

9.1 获取套餐列表（公开）

GET /billing/plans

响应（示例）：

{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440900",
        "code": "pro_monthly",
        "name": "Pro（月付）",
        "currency": "CNY",
        "amount_cents": 1999,
        "interval": "monthly",
        "included_units_per_period": 10000,
        "max_file_size_mb": 20,
        "max_files_per_batch": 50,
        "retention_days": 7,
        "features": { "webhook": true }
      }
    ]
  }
}

9.2 获取当前订阅

GET /billing/subscription
Authorization: Bearer <token>

9.3 获取当期用量

GET /billing/usage
Authorization: Bearer <token>

响应：

{
  "success": true,
  "data": {
    "period_start": "2025-01-01T00:00:00Z",
    "period_end": "2025-02-01T00:00:00Z",
    "used_units": 120,
    "included_units": 10000,
    "bonus_units": 500,
    "total_units": 10500,
    "remaining_units": 10380
  }
}

9.4 创建 Checkout（订阅/升级）

POST /billing/checkout
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <key>

请求体：

{ "plan_id": "550e8400-e29b-41d4-a716-446655440900" }

响应：

{ "success": true, "data": { "checkout_url": "https://pay.example.com/..." } }

9.5 打开客户 Portal（管理支付方式/取消订阅）

POST /billing/portal
Authorization: Bearer <token>

9.6 发票列表

GET /billing/invoices?page=1&limit=20
Authorization: Bearer <token>

10. Webhooks（支付回调）

无需登录；必须验签与幂等处理，详见 docs/billing.md 与 docs/security.md。

10.1 Stripe 回调（示例）

POST /webhooks/stripe
Content-Type: application/json
Stripe-Signature: t=...,v1=...

11. 管理员接口

需要管理员权限（role: admin）

11.1 获取系统统计

GET /admin/stats
Authorization: Bearer <admin_token>

11.2 用户管理（示例）

GET /admin/users?page=1&limit=20&search=keyword
Authorization: Bearer <admin_token>

11.3 系统配置

GET /admin/config
Authorization: Bearer <admin_token>

PUT /admin/config
Authorization: Bearer <admin_token>
Content-Type: application/json

11.4 任务管理

GET /admin/tasks?status=processing&page=1
Authorization: Bearer <admin_token>

POST /admin/tasks/{task_id}/cancel
Authorization: Bearer <admin_token>

11.5 计费管理（建议）

GET /admin/billing/subscriptions?page=1&limit=20
Authorization: Bearer <admin_token>

POST /admin/billing/credits
Authorization: Bearer <admin_token>
Content-Type: application/json

12. WebSocket（网站任务进度）

网站侧可用 WebSocket 或 SSE（SSE 更易穿透代理）。当前先保留 WebSocket 方案：

ws://your-domain.com/ws/tasks/{task_id}?token=<jwt_token>

消息（示例）：

{ "type": "progress", "data": { "task_id": "550e8400-e29b-41d4-a716-446655440200", "progress": 50, "completed_files": 5 } }
Reference in New Issue View Git Blame Copy Permalink