平台开放接口（Platform Open API）

Platform Open API 面向第三方平台的服务端集成。平台 Key 用于管理用户、项目和余额；项目 token_key 用于调用模型推理接口。

1. 基础信息

后端兼容直接在 Authorization 中传平台 Key，但推荐始终使用标准 Bearer 格式。平台 Key、所属 credential 或 platform client 被禁用，或 Key 已过期时，请求会失败。

平台 Key 仅用于本页管理接口，不能用于 /v1/* 模型推理接口。

2. 通用响应

成功响应：

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

失败响应：

{
  "success": false,
  "message": "错误信息"
}

当前实现中，业务成功和业务失败通常都返回 HTTP 200。调用方必须检查 success，不能仅根据 HTTP status 判断结果。

分页响应

日志和充值记录列表返回：

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": []
  }
}

3. 业务模型与额度

• 一个第三方平台对应一个 platform client 和一个或多个平台 Key。
• 一个平台可创建多个平台用户；接口返回的主键是 platform_user_id。
• 一个平台用户可创建多个项目；接口返回的主键是 platform_project_id。
• 每个项目绑定一个独立 Token。只有项目 upsert 会返回完整 token_key。
• 项目 Token 固定为永不过期、Token 自身无限额度、默认不限制模型。
• 项目调用仍受所属用户余额限制；真实可用余额是 user_quota_remaining。

额度字段使用整数 quota。LetAI 当前默认换算值为：

1 USD = 500000 quota

系统管理员可以修改 QuotaPerUnit。开放接口不会根据 amount 或 currency 自动换算，接入方应以平台当前配置为准，并显式传入 raw quota。

4. 状态与日志类型

状态值

禁用平台用户会同步禁用底层用户，从而阻断该用户的所有项目 Token。禁用项目只会同步禁用该项目对应的 Token。

日志类型

5. 接口总表

下文路径均相对于 /api/platform/open。

6. 用户接口

6.1 创建或获取平台用户

POST /users/upsert
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_user_id": "u_10001",
  "external_user_name": "Alice",
  "email": "alice@example.com",
  "metadata": {
    "channel": "partner-a"
  }
}

同一平台下已存在相同 external_user_id 时，接口返回原用户，并按本次请求更新非空的 external_user_name、email 和已传入的 metadata。未传 external_user_id 时，每次调用都会创建新用户。

关键响应字段：

{
  "platform_user_id": 101,
  "external_user_id": "u_10001",
  "external_user_name": "Alice",
  "local_user_id": 9001,
  "group": "default",
  "status": 1,
  "user_status": 1,
  "project_count": 0,
  "quota_total": 0,
  "quota_used": 0,
  "quota_remaining": 0,
  "request_count": 0,
  "email": "alice@example.com",
  "metadata": "{\"channel\":\"partner-a\"}"
}

metadata 在响应中是序列化后的 JSON 字符串；未设置时字段可能省略。

6.2 禁用或启用平台用户

POST /users/:platform_user_id/disable
POST /users/:platform_user_id/enable
Authorization: Bearer <platform-key>

两个接口均无请求体，返回最新用户概览。重复执行相同状态操作是幂等的。

6.3 查询用户概览

GET /users/:platform_user_id/summary
Authorization: Bearer <platform-key>

返回字段与用户 upsert 相同。额度语义：

7. 项目接口

7.1 创建或获取项目及 Token

POST /users/:platform_user_id/projects/upsert
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_project_id": "p_10001",
  "external_project_name": "客服机器人",
  "metadata": {
    "environment": "production"
  }
}

未传 external_project_id 时，每次调用都会创建新项目。平台用户或底层用户已禁用时不能创建项目。

成功响应中的 data：

{
  "platform_project_id": 201,
  "platform_user_id": 101,
  "external_project_id": "p_10001",
  "external_project_name": "客服机器人",
  "local_user_id": 9001,
  "token_id": 3001,
  "token_name": "客服机器人",
  "token_key": "<project-token-key>",
  "group": "default",
  "status": 1,
  "token_status": 1,
  "quota_limited_by": "user",
  "quota_used": 0,
  "user_quota_remaining": 5000000,
  "unlimited_quota": true,
  "expires_at": -1,
  "metadata": "{\"environment\":\"production\"}"
}

完整 token_key 只在项目 upsert 响应中返回。请在服务端安全保存；项目 summary、enable 和 disable 响应不会再次返回该字段。

7.2 禁用或启用项目

POST /projects/:platform_project_id/disable
POST /projects/:platform_project_id/enable
Authorization: Bearer <platform-key>

两个接口均无请求体，返回最新项目概览，但不包含 token_key。如果所属用户仍处于禁用状态，仅启用项目不能恢复模型调用。

7.3 查询项目概览

GET /projects/:platform_project_id/summary
Authorization: Bearer <platform-key>

返回项目概览，不包含 token_key。当前项目 Token 固定由用户余额限制，因此：

• quota_limited_by 为 user
• unlimited_quota 为 true
• quota_used 是该 Token 的累计消耗
• user_quota_remaining 是所属用户的当前真实余额
• expires_at 为 -1，表示永不过期

8. 资金接口

资金接口均要求平台用户和底层用户处于启用状态。amount、refund_amount 和 currency 仅用于审计或对账，不影响 quota 计算。

8.1 用户充值

POST /users/:platform_user_id/topups
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_order_id": "ord_20260727_0001",
  "quota": 5000000,
  "amount": "10.00",
  "currency": "USD",
  "remark": "套餐充值",
  "metadata": {
    "plan": "pro"
  }
}

重复 external_order_id 只有在所属用户、quota、amount、currency 均与原请求一致时才返回原记录，否则返回幂等冲突错误。

8.2 退款或冲正

POST /users/:platform_user_id/topups/refund
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_refund_id": "refund_20260727_0001",
  "external_order_id": "ord_20260727_0001",
  "refund_quota": 1000000,
  "refund_amount": "2.00",
  "currency": "USD",
  "remark": "部分退款"
}

累计退款不能超过原订单的充值 quota，用户当前余额也必须不小于本次 refund_quota。响应包含 refunded_quota_total 和 refundable_quota_remaining。

8.3 重置用户余额

POST /users/:platform_user_id/balance/reset
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_reset_id": "reset_20260727_0001",
  "target_quota": 2500000,
  "remark": "同步订阅余额"
}

external_reset_id 必填且最长 128 字符；target_quota 必填且必须大于或等于 0。响应包含 previous_quota、target_quota 和 quota_delta。

8.4 增减用户余额

POST /users/:platform_user_id/balance/adjust
Authorization: Bearer <platform-key>
Content-Type: application/json

{
  "external_adjust_id": "adjust_20260727_0001",
  "delta_quota": -500000,
  "remark": "人工扣减"
}

external_adjust_id 必填且最长 128 字符；delta_quota 不能为 0。正数增加余额，负数减少余额；余额最低截断到 0，不会变为负数。

响应中的 requested_delta_quota 是请求值，applied_delta_quota 是实际生效值。例如当前余额为 100、请求 -500 时，实际变动为 -100。

8.5 查询充值记录

GET /users/:platform_user_id/topups?p=1&page_size=20
Authorization: Bearer <platform-key>

该接口仅支持通用分页，不支持按订单号筛选。每条记录包含订单、quota、审计金额、创建时间和查询时的用户额度汇总。

9. 日志查询

GET /users/:platform_user_id/logs?p=1&page_size=20&type=2
GET /projects/:platform_project_id/logs?p=1&page_size=20&type=2
Authorization: Bearer <platform-key>

日志结果按最新优先排序。返回的 id 是当前分页结果中的展示序号，不是稳定的数据库日志 ID。出于安全考虑，channel_name 会被清空，other 中的管理员信息与拒绝原因会被移除。

10. 使用项目 Token 调用模型

curl --request POST \
  --url https://api.letai.run/v1/chat/completions \
  --header 'Authorization: Bearer <project-token-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

模型请求使用项目 token_key，不是平台 Key。项目或所属用户被禁用、用户余额不足时，模型调用会失败。

11. 幂等与接入建议

• 在调用侧持久化所有 external_* ID，并在重试时复用原请求参数。
• 记录 request_id、平台业务订单号和响应 message，便于对账与排错。
• 平台 Key 与项目 Token 分离存储并遵循最小权限原则。
• 资金请求超时后，使用相同幂等键重试，不要生成新订单号。
• metadata 响应按 JSON 字符串解析；空值字段可能因 omitempty 被省略。