概述

接口说明

本文档定义了用户端与AI进行交互的所有接口，包括：

• 用户认证（注册、登录、Token刷新）
• AI对话（发送消息、获取回复）
• 亲密度查询（等级、分数、状态）
• 动作执行（早安、晚安、特殊动作）
• 关系判定（表白、结拜等）
• 用户信息管理

产品简介

AI 灵魂伴侣是一个基于 AI 的虚拟陪伴应用，通过对话和互动培养用户与 AI 伴侣之间的关系。用户通过日常对话和执行特定动作来提升亲密度等级，解锁更多互动方式。

基础信息

• 开发环境: http://localhost:8081/v1
• 测试环境: https://nginx-0qs3.onrender.com/v1
• 生产环境: https://api.soulmate.ai/v1
• 协议: HTTP/HTTPS
• 内容类型: application/json
• 字符编码: UTF-8

认证方式

除认证接口外，所有接口都需要 JWT 认证。

获取 Token

通过 用户登录接口 获取访问令牌：

curl -X POST https://nginx-0qs3.onrender.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

响应会包含两个令牌：

• Access Token：用于 API 调用的身份验证
• Refresh Token：用于刷新过期的 Access Token

使用 Token

在请求头中添加 Authorization 字段：

Authorization: Bearer <access_token>

示例：

curl -X GET https://nginx-0qs3.onrender.com/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token 验证

如果 Token 无效或过期，API 返回 401 Unauthorized：

{
  "code": 10002,
  "message": "未授权：Token无效或已过期",
  "data": null
}

刷新 Token

当 Access Token 过期时，使用 刷新令牌接口 获取新 Token：

curl -X POST https://nginx-0qs3.onrender.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your_refresh_token"
  }'

Token 有效期

环境	Access Token	Refresh Token
开发环境	10年	10年
生产环境	24小时	7天

JWT Payload 结构

{
  "user_id": "uuid-string",
  "username": "string",
  "iat": 1234567890,
  "exp": 1234654290
}

快速开始

首次使用？查看 快速开始指南 了解如何注册用户和获取 Token。

通用响应格式

成功响应 (HTTP 200):

{
  "code": 0,
  "message": "success",
  "data": {
    // 具体业务数据
  }
}

错误响应 (HTTP 4xx/5xx):

{
  "code": 错误码,
  "message": "错误描述信息",
  "data": null
}

错误码表

错误码	HTTP状态码	说明
0	200	成功
10001	400	请求参数错误
10002	401	未授权（Token缺失或无效）
10003	403	禁止访问（权限不足）
10004	404	资源不存在
10005	409	资源冲突（如用户名已存在）
10006	422	业务逻辑错误（如冷却时间未到、条件不满足）
10007	429	请求过于频繁
50001	500	服务器内部错误
50002	503	服务暂时不可用