认证方式

所有 API 请求都需要在 Header 中携带 API Key 进行认证。你可以在开发者控制台中创建和管理 API Key。

Request Header

Authorization: Bearer modx-your_api_key_here

安全提示：API Key 等同于你的账户凭证，请勿在客户端代码或公开仓库中暴露。建议通过环境变量或服务端代理使用。

频率限制

每个 API Key 的默认调用频率为 60 次/分钟。超过限制将返回 429 状态码。

响应 Header 中包含以下频率限制信息：

Header	说明
`X-RateLimit-Limit`	当前时间窗口内的请求配额
`X-RateLimit-Remaining`	剩余可用请求数
`X-RateLimit-Reset`	配额重置时间（Unix 时间戳）

错误码

API 使用标准 HTTP 状态码表示请求结果。错误响应体包含详细错误信息。

状态码	类型	说明
400	Bad Request	请求参数错误
401	Unauthorized	未提供有效的 API Key
403	Forbidden	权限不足，无权访问该资源
404	Not Found	请求的资源不存在
429	Too Many Requests	请求频率超过限制
500	Internal Server Error	服务器内部错误

Response · 200 OK

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested mod was not found"
  }
}

获取模组详情

GET /v2/mods/:id

根据 ID 获取单个模组的详细信息。ID 支持三种格式，按优先级依次匹配：slug → short_id → UUID。

路径参数

参数	类型	必填	说明
`id`	string	是	模组标识，支持 slug、short_id 或 UUID

响应字段

字段	类型	说明
`id`	string	模组 short_id
`slug`	string\|null	模组 slug
`title`	string	模组名称
`summary`	string\|null	模组简介
`description`	string	模组完整描述（MD）
`version`	string\|null	当前版本（权重最高的文件版本）
`cover_image`	string\|null	封面图 URL
`banner_image`	string\|null	横幅图 URL
`author`	object\|null	作者信息（id, name, slug, avatar_url）
`reposted`	boolean	是否为转载作品
`original_author`	string\|null	原作者名称（仅转载时有值）
`co_authors`	object[]	联合创作者列表（仅已同意的）
`co_authors[].user`	object	创作者信息（id, name, slug, avatar_url）
`co_authors[].role`	string	职责角色，如 SCRIPTING、MODELING、TEXTURES 等
`categories`	object[]	分类列表（含所属游戏）
`categories[].name`	string	分类名称
`categories[].game`	string	分类所属游戏名称
`tags`	string[]	标签名称列表
`games`	string[]	所属游戏名称列表
`downloads`	integer	下载次数
`views`	integer	浏览次数
`like_count`	integer	点赞数
`comments_count`	integer	评论数
`collections_count`	integer	收藏数
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	更新时间（ISO 8601）

响应示例

Response · 200 OK

{
  "code": 0,
  "data": {
    "id": "a1b2c3",
    "slug": "cleo-script-pack",
    "title": "CLEO 实用脚本合集",
    "summary": "包含 50+ 常用 CLEO 脚本",
    "description": "<p>完整描述内容...</p>",
    "version": "2.1.0",
    "cover_image": "https://img.gtamodx.com/covers/abc.jpg",
    "banner_image": null,
    "author": {
      "id": "u1",
      "name": "ModMaster",
      "slug": "modmaster",
      "avatar_url": "https://img.gtamodx.com/avatars/u1.jpg"
    },
    "reposted": false,
    "original_author": null,
    "co_authors": [
      {
        "user": {
          "id": "u2",
          "name": "ArtistPro",
          "slug": "artistpro",
          "avatar_url": "https://img.gtamodx.com/avatars/u2.jpg"
        },
        "role": "MODELING"
      },
      {
        "user": {
          "id": "u3",
          "name": "ScriptHelper",
          "slug": "scripthelper",
          "avatar_url": null
        },
        "role": "SCRIPTING"
      }
    ],
    "categories": [
      { "name": "脚本", "game": "GTA San Andreas" },
      { "name": "工具", "game": "GTA San Andreas" }
    ],
    "tags": ["CLEO", "实用"],
    "games": ["GTA San Andreas"],
    "downloads": 12580,
    "views": 45230,
    "like_count": 892,
    "comments_count": 156,
    "collections_count": 340,
    "created_at": "2025-08-12T10:00:00Z",
    "updated_at": "2026-05-20T14:30:00Z"
  }
}

获取模组文件列表

GET /v2/mods/:id/files

获取指定模组的文件列表，按权重降序排列。ID 支持三种格式，按优先级依次匹配：slug → short_id → UUID。

路径参数

参数	类型	必填	说明
`id`	string	是	模组标识，支持 slug、short_id 或 UUID

查询参数

参数	类型	必填	说明
`type`	string	否	文件类型筛选，如 Main、Optional

响应字段

字段	类型	说明
`mod_id`	string	模组 short_id
`mod_title`	string	模组名称
`files`	object[]	文件列表
`files[].id`	string	文件 ID
`files[].filename`	string	原始文件名
`files[].display_filename`	string	显示文件名
`files[].size`	integer\|null	文件大小（字节）
`files[].version`	string\|null	文件版本
`files[].type`	string	文件类型（Main / Optional）
`files[].description`	string\|null	文件描述
`files[].download_count`	integer	下载次数
`files[].md5`	string\|null	文件 MD5 校验值
`files[].is_paid`	boolean	是否为付费文件
`files[].price`	integer	文件价格（免费为 0）
`files[].created_at`	string\|null	创建时间（ISO 8601）

响应示例

Response · 200 OK

{
  "code": 0,
  "data": {
    "mod_id": "a1b2c3",
    "mod_title": "CLEO 实用脚本合集",
    "files": [
      {
        "id": "f1e2d3c4",
        "filename": "cleo_pack_v2.oiv",
        "display_filename": "CLEO 脚本合集 v2",
        "size": 157286400,
        "version": "2.1.0",
        "type": "Main",
        "description": "主文件包",
        "download_count": 8900,
        "md5": "a1b2c3d4e5f6g7h8",
        "is_paid": false,
        "price": 0,
        "created_at": "2026-05-20T14:30:00Z"
      },
      {
        "id": "f2e3d4c5",
        "filename": "hotfix_patch.oiv",
        "display_filename": "热修复补丁",
        "size": 5242880,
        "version": "2.1.0",
        "type": "Optional",
        "description": "修复了启动崩溃问题",
        "download_count": 3200,
        "md5": "i9j0k1l2m3n4o5p6",
        "is_paid": false,
        "price": 0,
        "created_at": "2026-05-22T08:00:00Z"
      }
    ]
  }
}