User APIs

本页仅包含对外可见接口。Admin 接口见 internal 文档。

稳定接口清单

• GET /api/v1/ai/me
• GET /api/v1/ai/recommended-questions
• POST /api/v1/ai/chat/send
• POST /api/v1/ai/events
• GET /api/v1/ai/hot-topics
• GET /api/v1/news/hot
• GET /api/v1/news/topics
• POST /api/v1/news/refresh
• GET /api/v1/ai/points
• GET /api/v1/ai/points/ledger
• POST /api/v1/ai/points/exchange
• GET /api/v1/ai/subscription

---

GET /api/v1/ai/me

Method / Path

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

Header

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

Query

无

Request Body

无

Response 字段

Field	Type	Description
data.user_id	string	用户标识
data.balance_points	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/me" \
  -H "X-User-Token: demo-user-token"

示例响应（2026-04-07 实测）

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "user_id": "demo_user",
    "balance_points": 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

备注

• Demo 账号为演示高额度口径，正式接入时以平台真实额度为准。

---

GET /api/v1/ai/recommended-questions

Method / Path

• Method: GET
• Path: /api/v1/ai/recommended-questions
• Stability: stable

Header

Name	Required	Description
X-User-Token	Optional	可选（接口支持匿名访问）

Query

Name	Type	Required	Default	Notes
scene	string	No	home	场景
lang	string	No	zh	语言
limit	int	No	6	1~20

Request Body

无

Response 字段

Field	Type	Description
data.scene	string	场景
data.lang	string	语言
data.questions	array	推荐问题列表
data.questions[].content	string	问题文本
data.questions[].order_index	int	排序

示例请求

curl "https://api.juai.store/api/v1/ai/recommended-questions?scene=market&lang=zh&limit=5" \
  -H "X-User-Token: demo-user-token"

示例响应（截断）

{
  "success": true,
  "data": {
    "scene": "market",
    "lang": "zh",
    "questions": [
      {"content": "原油价格与美元指数通常是什么关系？", "order_index": 1}
    ]
  }
}

错误码

• 422: limit 越界（>20）

---

POST /api/v1/ai/chat/send

Method / Path

• Method: POST
• Path: /api/v1/ai/chat/send
• Stability: stable

Header

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

Query

无

Request Body

Field	Type	Required	Description
question	string	Yes	用户问题（1~2000）
session_id	int	No	会话 ID
page_context	string	No	场景上下文
token_symbol	string	No	可选资产符号

Response 字段（关键）

Field	Type	Description
data.message_id	int	消息 ID
data.session_id	int	会话 ID
data.answer	string	回答正文
data.route	string	路由
data.sub_intent	string	子意图
data.source_items	array	来源链接
data.points_cost	int	本次消耗积分
data.credits_remaining	int	剩余额度
data.model_name	string	模型名
data.latency_ms	int	延迟

示例请求

curl -X POST "https://api.juai.store/api/v1/ai/chat/send" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: demo-user-token" \
  -d '{"question":"你是谁"}'

示例响应（截断）

{
  "success": true,
  "data": {
    "route": "platform_faq",
    "sub_intent": "ai_product_faq",
    "model_name": "openai/gpt-4o-mini",
    "answer": "我是小JU（Ju AI）..."
  }
}

错误码

• 422: question 为空或格式错误
• 1005: 积分不足
• 1007: 外部模型调用失败

备注

• 文档应避免暴露内部 fallback 文案给终端用户。

---

POST /api/v1/ai/events

Method / Path

• Method: POST
• Path: /api/v1/ai/events
• Stability: stable

Header

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

Request Body

Field	Type	Required	Description
event_type	string	Yes	行为类型（最小长度 2）
session_id	int	No	会话 ID
message_id	int	No	消息 ID
route	string	No	路由
sub_intent	string	No	子意图
feedback_type	string	No	helpful/inaccurate 等
event_payload	object	No	扩展字段

Response 字段

Field	Type	Description
data.event_id	int/string	事件 ID
data.event_type	string	事件类型
data.accepted	bool	是否接收
data.stored	bool	是否已存储

示例请求

curl -X POST "https://api.juai.store/api/v1/ai/events" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: demo-user-token" \
  -d '{"event_type":"thumbs_up","session_id":1,"message_id":1,"feedback_type":"helpful"}'

示例响应

{"success":true,"code":0,"data":{"event_id":204,"event_type":"thumbs_up","accepted":true,"stored":true}}

错误码

• 422: event_type 过短等参数错误

---

GET /api/v1/ai/hot-topics

Method / Path

• Method: GET
• Path: /api/v1/ai/hot-topics
• Stability: stable

Header

Name	Required	Description
X-User-Token	Optional	可选

Query

Name	Type	Required	Default
days	int	No	1
limit	int	No	6

Request Body

无

Response 字段（关键）

Field	Type	Description
data.topics	array	热点话题
data.user_hot_questions	array	用户热点问题
data.sentiment_overview	object	情绪概览
data.refresh_meta	object	刷新元信息

示例请求

curl "https://api.juai.store/api/v1/ai/hot-topics?days=1&limit=6" \
  -H "X-User-Token: demo-user-token"

示例响应（截断）

{
  "success": true,
  "data": {
    "topics": [
      {"topic": "BTC / ETH 强弱与市场波动", "heat": 44.38}
    ],
    "sentiment_overview": {"dominant": "中性"},
    "refresh_meta": {"last_full_sync_at": "2026-04-06T18:21:38.431126+00:00"}
  }
}

错误码

• 正常情况下异常会降级为 fallback 快照，不直接抛 500 给前端。
• 422: 参数越界（如 limit 不在范围内）

---

GET /api/v1/news/hot

Method / Path

• Method: GET
• Path: /api/v1/news/hot
• Stability: stable

Header

Name	Required	Description
-	No	无业务必填 Header

Query

Name	Type	Required	Default
limit	int	No	10
hours	int	No	48

Request Body

无

Response 字段

Field	Type	Description
data.news	array	新闻列表
data.total	int	总数

示例请求

curl "https://api.juai.store/api/v1/news/hot?limit=5"

示例响应（截断）

{
  "success": true,
  "data": {
    "news": [
      {"title": "Bitcoin has room to rally, but there's a catch"}
    ],
    "total": 5
  }
}

错误码

• 422: 参数越界（如 limit 非法）

备注

• 该接口无鉴权依赖，适合首页公共热点展示。

---

GET /api/v1/news/topics

Method / Path

• Method: GET
• Path: /api/v1/news/topics
• Stability: stable

Query

Name	Type	Required	Default
limit	int	No	5
lang	string	No	zh

Header

Name	Required	Description
-	No	无业务必填 Header

Request Body

无

Response 字段

Field	Type	Description
data.topics	array	聚类主题
data.total	int	总数

示例请求

curl "https://api.juai.store/api/v1/news/topics?limit=5&lang=zh"

示例响应（截断）

{
  "success": true,
  "data": {
    "topics": [
      {"title": "Bitcoin has room to rally, but there's a catch"}
    ],
    "total": 5
  }
}

错误码

• 422: 参数校验失败

备注

• question_suggestions 可直接喂给推荐问题模块。

---

POST /api/v1/news/refresh

Method / Path

• Method: POST
• Path: /api/v1/news/refresh
• Stability: stable

Header

Name	Required	Description
X-User-Token	Yes (business)	用户鉴权

Query

Name	Type	Required	Default	Notes
mode	string	No	view	view 轻量刷新；full 全量同步

Request Body

无

Response 字段（关键）

Field	Type	Description
data.refresh_mode	string	刷新模式
data.news_updated_count	int	新闻更新条数
data.notice_updated_count	int	公告/帮助中心更新条数
data.last_full_sync_at	string	最近全量同步时间
data.sentiment_updated_at	string	情绪指标时间

示例请求

curl -X POST "https://api.juai.store/api/v1/news/refresh?mode=view" \
  -H "X-User-Token: demo-user-token"

示例响应（截断）

{
  "success": true,
  "data": {
    "refresh_mode": "view",
    "news_updated_count": 0,
    "notice_updated_count": 0,
    "topic_rebuild_count": 6,
    "sentiment_updated_at": "2026-04-07T00:00:00+00:00"
  }
}

错误码

• 401: 缺少用户 token

备注

• mode=full 为长任务，文档应标注“可能耗时较长”。

---

GET /api/v1/ai/points

Method / Path

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

Header

Name	Required	Description
X-User-Token	Yes (business)	用户鉴权

Query

无

Request Body

无

Response 字段

Field	Type	Description
data.balance	int	积分余额
data.total_earned	int	累计获得
data.total_spent	int	累计消耗
data.next_reset_at	string	重置时间

示例请求

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

示例响应

{
  "success": true,
  "data": {
    "balance": 9999999,
    "free_daily_quota": 999999,
    "free_daily_used": 0,
    "remaining_free_quota": 999999
  }
}

错误码

• 401: 未登录

备注

• 与 /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)	用户鉴权

Query

Name	Type	Required	Default
page	int	No	1
page_size	int	No	20

Response 字段

Field	Type	Description
data.items[]	array	流水
data.items[].delta	int	变化值
data.items[].type	string	类型
data.items[].ref_id	string	关联请求
data.total	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": [
      {"delta": 15, "type": "exchange", "ref_id": "e2e4019a-..."}
    ],
    "total": 1
  }
}

错误码

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

备注

• 建议前端按 created_at 倒序展示。

---

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)	用户鉴权

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 非法

备注

• 兑换后会写入 points ledger。

---

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)	用户鉴权

Query

无

Request Body

无

Response 字段

Field	Type	Description
data.status	string	订阅状态
data.plan	string	套餐
data.features	object	功能集

示例请求

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}
  }
}

错误码

• 401: 未登录

备注

• 记忆能力等高级功能由订阅特性控制。

---

已实现但实验性接口

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

Method / Path

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

Header

Name	Required
Content-Type	Yes
X-User-Token	Yes (business)

Request Body

Field	Type	Required
trade_type	string	Yes
volume_usd	float	Yes
ref_id	string	Yes

当前状态说明

• Staging 实测仍可能返回 500。
• 本接口不应放入“稳定可用”分组。