Soulmate API

Appearance

快速开始 ​

本指南将帮助你快速开始使用 Soulmate API。

前提条件 ​

  • 可访问的 Soulmate API 服务端点
  • 支持 HTTP 请求的工具（如 cURL、Postman、或编程语言的 HTTP 客户端）

API 端点 ​

根据你的环境选择对应的端点：

  • 开发环境: http://localhost:8081/v1
  • 测试环境: https://nginx-0qs3.onrender.com/v1
  • 生产环境: https://api.soulmate.ai/v1

第一步：注册用户 ​

首先，你需要注册一个用户账号。

请求示例 ​

bash
curl -X POST https://nginx-0qs3.onrender.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myusername",
    "password": "mypassword123"
  }'
javascript
const response = await fetch('https://nginx-0qs3.onrender.com/v1/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'myusername',
    password: 'mypassword123'
  })
});

const data = await response.json();
console.log('User created:', data.data.user_id);
python
import requests

response = requests.post(
    'https://nginx-0qs3.onrender.com/v1/auth/register',
    json={
        'username': 'myusername',
        'password': 'mypassword123'
    }
)

data = response.json()
print('User created:', data['data']['user_id'])

响应示例 ​

json
{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": "95af8297-ae59-4802-bcce-b0e984195d48",
    "username": "myusername",
    "created_at": "2025-10-03T12:29:13Z"
  }
}

第二步：获取访问令牌 ​

注册成功后，使用用户名和密码登录获取访问令牌（Access Token）。

请求示例 ​

bash
curl -X POST https://nginx-0qs3.onrender.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myusername",
    "password": "mypassword123"
  }'
javascript
const response = await fetch('https://nginx-0qs3.onrender.com/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'myusername',
    password: 'mypassword123'
  })
});

const data = await response.json();
const accessToken = data.data.access_token;
const refreshToken = data.data.refresh_token;

console.log('Access Token:', accessToken);
python
import requests

response = requests.post(
    'https://nginx-0qs3.onrender.com/v1/auth/login',
    json={
        'username': 'myusername',
        'password': 'mypassword123'
    }
)

data = response.json()
access_token = data['data']['access_token']
refresh_token = data['data']['refresh_token']

print('Access Token:', access_token)

响应示例 ​

json
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

重要

  • Access Token：用于后续 API 调用的身份验证
  • Refresh Token：用于刷新过期的 Access Token
  • expires_in：Access Token 的有效期（秒）

第三步：使用 Token 调用 API ​

获得 Access Token 后，你可以调用需要认证的 API 接口。在请求头中添加 Authorization: Bearer <access_token>。

示例：发送消息 ​

bash
curl -X POST https://nginx-0qs3.onrender.com/v1/conversations/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "content": "你好！"
  }'
javascript
const response = await fetch('https://nginx-0qs3.onrender.com/v1/conversations/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    content: '你好！'
  })
});

const data = await response.json();
console.log('AI回复:', data.data.ai_response);
python
import requests

response = requests.post(
    'https://nginx-0qs3.onrender.com/v1/conversations/messages',
    headers={
        'Authorization': f'Bearer {access_token}'
    },
    json={
        'content': '你好！'
    }
)

data = response.json()
print('AI回复:', data['data']['ai_response'])

示例：获取用户状态 ​

bash
curl -X GET https://nginx-0qs3.onrender.com/v1/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
javascript
const response = await fetch('https://nginx-0qs3.onrender.com/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const data = await response.json();
console.log('当前等级:', data.data.level.name);
console.log('亲密度:', data.data.intimacy.score);
python
import requests

response = requests.get(
    'https://nginx-0qs3.onrender.com/v1/users/me',
    headers={
        'Authorization': f'Bearer {access_token}'
    }
)

data = response.json()
print('当前等级:', data['data']['level']['name'])
print('亲密度:', data['data']['intimacy']['score'])

Token 管理 ​

Token 验证 ​

如果 Access Token 无效或过期，API 将返回 401 Unauthorized 错误：

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

刷新 Token ​

当 Access Token 过期时，使用 Refresh Token 获取新的 Access Token：

bash
curl -X POST https://nginx-0qs3.onrender.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'
javascript
const response = await fetch('https://nginx-0qs3.onrender.com/v1/auth/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refresh_token: refreshToken
  })
});

const data = await response.json();
const newAccessToken = data.data.access_token;
const newRefreshToken = data.data.refresh_token;
python
import requests

response = requests.post(
    'https://nginx-0qs3.onrender.com/v1/auth/refresh',
    json={
        'refresh_token': refresh_token
    }
)

data = response.json()
new_access_token = data['data']['access_token']
new_refresh_token = data['data']['refresh_token']

建议

建议在收到 401 错误时自动调用刷新接口，这样可以无缝地续期用户会话。

下一步 ​

现在你已经可以开始使用 Soulmate API 了！

常见问题 ​

如何处理 Token 过期？ ​

建议在应用中实现自动刷新机制：

  1. 保存 Access Token 和 Refresh Token
  2. 每次 API 调用前检查 Token 是否快过期
  3. 如果收到 401 错误，使用 Refresh Token 获取新 Token
  4. 用新 Token 重试原请求

Token 有效期是多久？ ​

  • 开发环境：Access Token 和 Refresh Token 均为 10 年
  • 生产环境：
    • Access Token：24 小时
    • Refresh Token：7 天

如何安全存储 Token？ ​

  • 前端应用：使用 localStorage 或 sessionStorage
  • 移动应用：使用系统提供的安全存储（如 iOS Keychain、Android Keystore）
  • 服务端应用：使用环境变量或安全配置文件
  • ⚠️ 不要将 Token 硬编码在代码中或提交到版本控制系统

Released under the MIT License.

Copyright © 2024-present Soulmate