{
  "name": "OpenTapTap Resource API",
  "version": "1.0.0",
  "description": "CC0 游戏素材库查询 API",
  "site": "https://res.opentaptap.dev",
  "r2_base": "https://api.res.opentaptap.dev",
  "mcp_server": "https://mcp.res.opentaptap.dev/mcp",
  "license": "CC0 1.0",
  "endpoints": [
    {
      "path": "/api/manifest",
      "method": "GET",
      "description": "服务自描述（本端点）",
      "params": []
    },
    {
      "path": "/api/categories",
      "method": "GET",
      "description": "获取全部分类列表 + 包数量",
      "params": []
    },
    {
      "path": "/api/tags",
      "method": "GET",
      "description": "获取全部标签（可按 group 过滤）+ 计数",
      "params": [
        {
          "name": "group",
          "type": "string",
          "required": false,
          "values": [
            "style",
            "type",
            "content",
            "format"
          ],
          "description": "按分组过滤"
        }
      ]
    },
    {
      "path": "/api/packs",
      "method": "GET",
      "description": "素材包列表（支持过滤/分页/排序）",
      "params": [
        {
          "name": "category",
          "type": "string",
          "required": false,
          "description": "分类名"
        },
        {
          "name": "tag",
          "type": "string",
          "required": false,
          "description": "标签名（可多次传参实现 AND 过滤）"
        },
        {
          "name": "format",
          "type": "string",
          "required": false,
          "description": "格式（PNG/OGG/3D/SVG/TTF）"
        },
        {
          "name": "q",
          "type": "string",
          "required": false,
          "description": "关键字搜索"
        },
        {
          "name": "page",
          "type": "int",
          "required": false,
          "default": 1,
          "description": "页码"
        },
        {
          "name": "size",
          "type": "int",
          "required": false,
          "default": 20,
          "max": 100,
          "description": "每页数量"
        },
        {
          "name": "sort",
          "type": "string",
          "required": false,
          "values": [
            "files",
            "name",
            "category"
          ],
          "default": "files",
          "description": "排序方式"
        }
      ]
    },
    {
      "path": "/api/packs/:slug",
      "method": "GET",
      "description": "素材包详情 + 标签 + 文件示例",
      "params": [
        {
          "name": "slug",
          "type": "string",
          "required": true,
          "description": "素材包 URL 标识符"
        }
      ]
    },
    {
      "path": "/api/packs/:slug/files",
      "method": "GET",
      "description": "素材包内文件列表（分页 + 格式过滤）",
      "params": [
        {
          "name": "slug",
          "type": "string",
          "required": true
        },
        {
          "name": "ext",
          "type": "string",
          "required": false,
          "description": "按扩展名过滤（png/ogg/glb/...）"
        },
        {
          "name": "kind",
          "type": "string",
          "required": false,
          "values": [
            "png",
            "audio",
            "model3d",
            "svg",
            "font",
            "code",
            "other"
          ],
          "description": "按类型过滤"
        },
        {
          "name": "page",
          "type": "int",
          "required": false,
          "default": 1
        },
        {
          "name": "size",
          "type": "int",
          "required": false,
          "default": 50,
          "max": 100
        }
      ]
    },
    {
      "path": "/api/files/:id",
      "method": "GET",
      "description": "单文件元数据 + R2 直链（302 重定向到 R2）",
      "params": [
        {
          "name": "id",
          "type": "int",
          "required": true
        }
      ]
    },
    {
      "path": "/api/search",
      "method": "GET",
      "description": "跨包关键字搜索（搜索包名/notes/slug）",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true
        },
        {
          "name": "page",
          "type": "int",
          "required": false,
          "default": 1
        },
        {
          "name": "size",
          "type": "int",
          "required": false,
          "default": 20,
          "max": 100
        }
      ]
    },
    {
      "path": "/api/suggest",
      "method": "GET",
      "description": "标签/包名自动补全",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true
        }
      ]
    },
    {
      "path": "/api/health",
      "method": "GET",
      "description": "健康检查",
      "params": []
    }
  ],
  "tag_groups": {
    "style": "艺术风格（像素风/卡通风/等距/俯视等）",
    "type": "游戏类型（平台跳跃/射击/RPG/赛车等）",
    "content": "素材内容（UI/角色/载具/瓦片等）",
    "format": "文件格式（PNG/SVG/OGG/TTF/3D）"
  },
  "how_to_use": {
    "step_1": "GET /api/tags 了解可用标签",
    "step_2": "GET /api/packs?tag=像素风&tag=平台跳跃 按标签过滤素材包",
    "step_3": "从返回结果中取 r2_url 或 preview_url 直接下载文件"
  },
  "examples": {
    "curl_search": "curl \"https://res.opentaptap.dev/api/packs?tag=像素风&page=1&size=5\"",
    "curl_pack": "curl \"https://res.opentaptap.dev/api/packs/uipack_fixed\"",
    "curl_file": "curl -L \"https://res.opentaptap.dev/api/files/1234\""
  },
  "response_format": "JSON（默认）或 Markdown（Accept: text/markdown）",
  "cors": "enabled (*)"
}