GTA数据库API调用文档

概述

本接口用于外部应用读取用户的 GTA Online 车库数据。采用双层认证机制，需同时提供项目密钥和用户个人令牌。

Base URL: https://www.antwen.cn

认证方式

Header	说明	获取方式
`X-API-Key`	项目密钥	由管理员分配给你的项目（仅支持底部联系我们提交反馈申请）
`X-User-Token`	用户个人令牌	用户在我的资料 → API 令牌中自行生成

[!IMPORTANT] 两个 Header 缺一不可，否则返回 401 错误。

接口

获取用户车库数据

GET /api/external/garage
GET /api/external/garage?characterId=<角色ID>

请求参数

参数	位置	必填	说明
`X-API-Key`	Header	✅	项目密钥
`X-User-Token`	Header	✅	用户个人令牌
`characterId`	Query	❌	角色 ID。单角色用户可不传；多角色用户必须指定

多角色支持

本系统支持一个账号下拥有多个 GTA 角色。API 的行为取决于用户的角色数量：

场景一：用户只有 1 个角色

直接返回车库数据，无需传 characterId。

场景二：用户有多个角色，未传 `characterId`

返回角色列表，提示调用方选择角色：

{
  "success": true,
  "multipleCharacters": true,
  "message": "该用户拥有多个角色，请通过 ?characterId=xxx 指定角色",
  "characters": [
    {
      "characterId": 2,
      "characterName": "一角色",
      "platform": "PC增强版",
      "slot": 1
    },
    {
      "characterId": 15,
      "characterName": "二角色",
      "platform": "PS5",
      "slot": 2
    }
  ]
}

场景三：传了 `characterId`

返回指定角色的车库数据。如果 ID 无效或不属于该用户，返回 403 并附带可用角色列表。

响应格式

成功响应（车库数据）

{
  "success": true,
  "data": {
    "username": "Dinghy",
    "totalVehicles": 45,
    "totalGarages": 12,
    "garages": [
      {
        "garageId": "office_floor1",
        "garageName": "花园银行西岸 - 1层",
        "vehicles": [
          {
            "vehicleId": "1761305393315-hoq9svyq9",
            "manufacturer": "绝品",
            "name": "卫士 GTS"
          },
          {
            "vehicleId": "1772160954658-gj757eix3",
            "manufacturer": "诗津",
            "name": "白鸟竞速版"
          }
        ]
      }
    ]
  }
}

字段说明

字段	类型	说明
`success`	boolean	请求是否成功
`data.username`	string	用户昵称或用户名
`data.totalVehicles`	number	车辆总数
`data.totalGarages`	number	有车辆的车库数量
`data.garages`	array	车库列表
`data.garages[].garageId`	string	车库唯一标识符
`data.garages[].garageName`	string	车库显示名称（含地址和楼层）
`data.garages[].vehicles`	array	该车库中的车辆列表
`data.garages[].vehicles[].vehicleId`	string	车辆唯一 ID
`data.garages[].vehicles[].manufacturer`	string	车辆制造商名称（中文）
`data.garages[].vehicles[].name`	string	车辆名称（中文）

错误响应

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

HTTP 状态码	error	说明
`401`	`Invalid API key`	项目密钥无效或缺失
`401`	`Missing user token`	未提供用户令牌
`401`	`Invalid or inactive user token`	用户令牌无效、已删除或已禁用
`403`	`Invalid characterId...`	角色 ID 不属于该用户（响应中包含可用角色列表）
`405`	`Method not allowed`	请求方法不是 GET
`500`	`Internal server error`	服务器内部错误

典型调用流程

┌─────────────────────────────────────────────────┐
│  1. 首次调用（不传 characterId）                   │
│     GET /api/external/garage                     │
│                                                  │
│  ┌─ 单角色用户 ─→ 直接返回车库数据                  │
│  └─ 多角色用户 ─→ 返回角色列表                      │
│                                                  │
│  2. 多角色时，选择角色后再次调用                      │
│     GET /api/external/garage?characterId=15       │
│     → 返回该角色的车库数据                          │
└─────────────────────────────────────────────────┘

代码示例

Python

import requests

API_KEY = "YOUR_API_KEY"
USER_TOKEN = "用户在网站上生成的令牌"
BASE_URL = "https://www.antwen.cn"

headers = {
    "X-API-Key": API_KEY,
    "X-User-Token": USER_TOKEN
}

# 第一步：查询（自动判断单角色/多角色）
response = requests.get(f"{BASE_URL}/api/external/garage", headers=headers)
data = response.json()

if data.get("multipleCharacters"):
    # 多角色：展示角色列表，让用户选择
    print("该用户有多个角色：")
    for c in data["characters"]:
        print(f"  ID={c['characterId']}  {c['characterName']}  ({c.get('platform', '未知平台')})")

    # 选择角色后再次请求
    char_id = data["characters"][0]["characterId"]
    response = requests.get(
        f"{BASE_URL}/api/external/garage?characterId={char_id}",
        headers=headers
    )
    data = response.json()

if data["success"] and "data" in data:
    print(f"用户: {data['data']['username']}")
    print(f"总车辆数: {data['data']['totalVehicles']}")
    for garage in data["data"]["garages"]:
        print(f"\n{garage['garageName']} ({len(garage['vehicles'])} 辆)")
        for v in garage["vehicles"]:
            print(f"{v['manufacturer']} {v['name']}")

JavaScript (Node.js)

const headers = {
  'X-API-Key': 'YOUR_API_KEY',
  'X-User-Token': '用户在网站上生成的令牌'
};

// 第一步：查询
let response = await fetch('https://www.antwen.cn/api/external/garage', { headers });
let data = await response.json();

// 多角色处理
if (data.multipleCharacters) {
  console.log('多角色用户，可用角色：', data.characters);
  const charId = data.characters[0].characterId;

  response = await fetch(
    `https://www.antwen.cn/api/external/garage?characterId=${charId}`,
    { headers }
  );
  data = await response.json();
}

if (data.success && data.data) {
  console.log(`用户: ${data.data.username}`);
  console.log(`总车辆数: ${data.data.totalVehicles}`);
  data.data.garages.forEach(garage => {
    console.log(`${garage.garageName}: ${garage.vehicles.length} 辆`);
  });
}

curl

# 查询（单角色直接返回数据，多角色返回角色列表）
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-User-Token: USER_TOKEN" \
     https://www.antwen.cn/api/external/garage

# 指定角色查询
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-User-Token: USER_TOKEN" \
     "https://www.antwen.cn/api/external/garage?characterId=15"

注意事项

[!NOTE]

接口支持 CORS 跨域调用，可在前端直接请求

车辆名称和制造商均为简体中文

garageId 为系统内部标识，格式如 apt1、office_floor1、nightclub_floor4

vehicleId 是用户级唯一 ID，同一辆车在不同用户间 ID 不同

characterId 是系统内部用户 ID（角色也是独立的用户记录）

[!WARNING]

用户可随时在网站上删除令牌，删除后该令牌立即失效

请勿将 X-API-Key 暴露在客户端代码中

每个用户最多可生成 5 个令牌

用户操作指引

用户需要在 GTA数据库网站上生成个人令牌：

登录 www.antwen.cn
点击右上角头像，进入个人信息
左侧选择 API 令牌
点击 生成令牌，填写名称后生成
立即复制保存令牌（令牌只显示一次）
将令牌填入外部应用的配置中

攻略GTA数据库API调用文档

概述

认证方式

接口

获取用户车库数据

请求参数

多角色支持

场景一：用户只有 1 个角色

场景二：用户有多个角色，未传 `characterId`

场景三：传了 `characterId`

响应格式

成功响应（车库数据）

字段说明

错误响应

典型调用流程

代码示例

Python

JavaScript (Node.js)

curl

注意事项

用户操作指引

评论 (3)

攻略GTA数据库API调用文档

概述

认证方式

接口

获取用户车库数据

请求参数

多角色支持

场景一：用户只有 1 个角色

场景二：用户有多个角色，未传 characterId

场景三：传了 characterId

响应格式

成功响应（车库数据）

字段说明

错误响应

典型调用流程

代码示例

Python

JavaScript (Node.js)

curl

注意事项

用户操作指引

评论 (3)

场景二：用户有多个角色，未传 `characterId`

场景三：传了 `characterId`