Skip to content

Platform Integration APIs

本章聚焦 JuAI 与平台账户、额度、积分体系的接口。

状态分层

已实现且稳定

  • GET /api/v1/ai/points
  • GET /api/v1/ai/points/ledger
  • POST /api/v1/ai/points/exchange
  • GET /api/v1/ai/subscription

已实现但实验性

  • POST /api/v1/ai/points/trade-reward

当前在 Staging 实测仍可能返回 500，只标注为 experimental / unstable。

规划中

  • 积分管理：grant / deduct / reset
  • 活动积分同步：activity points sync
  • 交易活动积分、任务奖励联动

GET /api/v1/ai/points

Method / Path

  • Method: GET
  • Path: /api/v1/ai/points
  • Stability: stable
Name Required Description
X-User-Token Yes (business) 用户登录态 token

Query 参数

无

Request Body

无

Response 字段表

Field Type Description
data.balance int 当前积分余额
data.total_earned int 累计获得积分
data.total_spent int 累计消耗积分
data.free_daily_quota int 每日免费次数
data.free_daily_used int 今日已使用免费次数
data.remaining_free_quota int 今日剩余免费次数
data.next_reset_at string 下次重置时间

示例请求

curl "https://api.juai.store/api/v1/ai/points" \
  -H "X-User-Token: demo-user-token"

示例响应

{
  "success": true,
  "code": 0,
  "data": {
    "balance": 9999999,
    "free_daily_quota": 999999,
    "free_daily_used": 0,
    "remaining_free_quota": 999999,
    "next_reset_at": "2026-04-07T17:00:00+00:00"
  }
}

错误码

  • 401: 未登录或 X-User-Token 无效

说明备注

  • 此接口用于前台额度栏展示，建议与 /api/v1/ai/me 做一致性校验。

GET /api/v1/ai/points/ledger

Method / Path

  • Method: GET
  • Path: /api/v1/ai/points/ledger
  • Stability: stable

Header

Name Required Description
X-User-Token Yes (business) 用户登录态 token

Query 参数

Name Type Required Default Notes
page int No 1 从 1 开始
page_size int No 20 1~100

Request Body

无

Response 字段表

Field Type Description
data.items[] array 流水条目
data.items[].id int 流水 ID
data.items[].delta int 增减值
data.items[].type string 流水类型
data.items[].description string 描述
data.items[].ref_id string 关联请求 ID
data.items[].created_at string 创建时间
data.total int 总条数
data.page int 当前页
data.page_size int 每页条数

示例请求

curl "https://api.juai.store/api/v1/ai/points/ledger?page=1&page_size=5" \
  -H "X-User-Token: demo-user-token"

示例响应（截断）

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "delta": 15,
        "type": "exchange",
        "ref_id": "e2e4019a-..."
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 5
  }
}

错误码

  • 401: 未登录
  • 422: 分页参数非法

说明备注

  • 建议前端展示字段：created_at, type, delta, balance_after(如后续扩展)。

POST /api/v1/ai/points/exchange

Method / Path

  • Method: POST
  • Path: /api/v1/ai/points/exchange
  • Stability: stable

Header

Name Required Description
Content-Type Yes application/json
X-User-Token Yes (business) 用户登录态 token

Query 参数

无

Request Body

Field Type Required Description
ju_amount float Yes 兑换 JU 数量，必须 > 0

Response 字段表

Field Type Description
data.ju_amount float 输入兑换数量
data.points_earned int 获得积分
data.balance_after int 兑换后积分余额
data.exchange_rate int 当前兑换比率

示例请求

curl -X POST "https://api.juai.store/api/v1/ai/points/exchange" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: demo-user-token" \
  -d '{"ju_amount":1.5}'

示例响应

{
  "success": true,
  "data": {
    "ju_amount": 1.5,
    "points_earned": 15,
    "balance_after": 15,
    "exchange_rate": 10
  }
}

错误码

  • 401: 未登录
  • 422: 参数校验失败（如 ju_amount <= 0）
  • 1009: 业务无效请求（预留）

说明备注

  • 正常成功后应可在 points/ledger 查到 exchange 流水。

GET /api/v1/ai/subscription

Method / Path

  • Method: GET
  • Path: /api/v1/ai/subscription
  • Stability: stable

Header

Name Required Description
X-User-Token Yes (business) 用户登录态 token

Query 参数

无

Request Body

无

Response 字段表

Field Type Description
data.status string 订阅状态
data.plan string 当前方案
data.started_at string/null 开始时间
data.expires_at string/null 过期时间
data.features object 功能开关集合
data.is_active bool 是否有效

示例请求

curl "https://api.juai.store/api/v1/ai/subscription" \
  -H "X-User-Token: demo-user-token"

示例响应

{
  "success": true,
  "data": {
    "status": "free",
    "plan": "free",
    "features": {
      "memory": false,
      "advanced_research": false
    },
    "is_active": false
  }
}

错误码

  • 401: 未登录

说明备注

  • 用于前端控制“记忆/高级研究”等功能显隐。

POST /api/v1/ai/points/trade-reward（Experimental）

Method / Path

  • Method: POST
  • Path: /api/v1/ai/points/trade-reward
  • Stability: experimental / unstable

Header

Name Required Description
Content-Type Yes application/json
X-User-Token Yes (business) 用户登录态 token

Query 参数

无

Request Body

Field Type Required Description
trade_type string Yes spot / futures
volume_usd float Yes 成交额
ref_id string Yes 去重标识

Response 字段表

Field Type Description
data.points_earned int 奖励积分
data.ref_id string 关联标识

示例请求

curl -X POST "https://api.juai.store/api/v1/ai/points/trade-reward" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: demo-user-token" \
  -d '{"trade_type":"spot","volume_usd":120.5,"ref_id":"docs-api-test-001"}'

示例响应（当前不稳定）

{"code":500,"detail":"服务内部错误，请稍后重试"}

错误码

  • 500: 当前 Staging 可复现，尚未稳定

说明备注

  • 该接口已实现但不稳定，严禁在对外文档中归入稳定能力。

平台接入字段定义草案

用户身份

  • exchange_user_id
  • platform_uid
  • session_token
  • kyc_level
  • vip_level
  • region
  • language

AI 额度

  • free_daily_quota
  • free_daily_used
  • remaining_free_quota
  • next_reset_at
  • quota_timezone（建议 UTC+8）

AI 积分

  • balance_points
  • activity_points
  • frozen_points
  • points_expire_at

流水

  • ledger_id
  • exchange_user_id
  • ledger_type：grant | deduct | reset | activity_reward | chat_cost
  • ledger_source：daily_quota | trade_activity | campaign | manual_adjustment | chat_send
  • delta_points
  • balance_after
  • reference_id
  • created_at

问答消耗

  • route
  • sub_intent
  • points_cost
  • message_id
  • session_id
  • request_id

数据覆盖现状说明

  • help_center_en = 0 作为数据覆盖现状记录，不定义为 API bug。