甜奈周边社区 API v1.0 接口文档

🌍 全局接入规范

基准地址 (Base URL)

https://tiannai.org/api/v1/api.php

请求方式 & 格式

支持 GET / POST
返回 application/json

统一响应结构

{
  "code": 200,          // 状态码：200成功，400参数错误，404查无数据，500异常
  "msg": "success",     // 状态说明或错误提示
  "data": {}            // 核心数据体（数组或对象）
}

GET/POST

1. 获取模特列表 (大厅)

分页获取平台所有模特数据，按评分和热度排序，已剔除敏感字段并格式化标签。

请求参数

参数名	类型	必填	默认值	说明
action	string	是	get_models	路由标识
page	int	否	1	当前页码
limit	int	否	20	每页数据条数

返回示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "星野奈奈",
        "avatar": "https://...",
        "avg_score": "4.9",
        "total_wishes": 345,
        "latest_event_name": "2023萤火虫动漫游戏嘉年华",
        "latest_event_id": 102,
        "tags_list": ["JK", "日常", "甜美"]
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 45,
      "total_pages": 3
    }
  }
}

GET/POST

2. 获取模特详细档案及图库

获取模特的官方档案、综合评分、去重后的参展履历，以及官方/UGC双子图库。

请求参数

参数名	类型	必填	说明
action	string	是	get_model_detail
id	int	是	目标模特的 ID
viewer_uid	int	否	当前查看者的用户ID (判定打榜状态)
is_admin	int	否	1/0，为1时透视匿名评价者信息

返回示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "base_info": {
      "id": 1,
      "name": "星野奈奈",
      "avatar": "https://...",
      "tags_list": ["JK", "甜美"]
    },
    "interaction": {
      "has_wished": false,
      "total_wishes": 345,
      "computed_score": "4.8"
    },
    "events_history": [
      {
        "event_id": 102,
        "name": "2023萤火虫动漫游戏嘉年华",
        "event_date": "2023-10-01"
      }
    ],
    "galleries": {
      "official_list": ["https://img1.jpg"],
      "ugc_list": [
        {
          "review_id": 56,
          "cover_image": "https://ugc1.jpg",
          "image_count": 2,
          "author": {
            "uid": 10086,
            "name": "摄影老法师",
            "is_anon_perspective": false
          }
        }
      ]
    }
  }
}

GET/POST

3. 获取活动大厅列表

分页获取活动列表，支持全文超级检索（活动名/模特名/评价内容）和日期精准筛选。

请求参数

参数名	类型	必填	说明
action	string	是	get_events
keyword	string	否	搜索关键词
date	string	否	日期筛选，格式：YYYY-MM-DD
page	int	否	当前页码，默认 1
limit	int	否	每页数据条数，默认 9

返回示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "event_id": 102,
        "name": "2023萤火虫动漫游戏嘉年华",
        "event_date": "2023-10-01",
        "cover_image": "https://...",
        "review_count": 15,
        "is_past": true,
        "status_text": "已归档"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 9,
      "total": 30,
      "total_pages": 4
    }
  }
}

GET/POST

4. 获取活动详情及关联评价

获取活动基础信息、关联官方/UGC模特，以及该活动下所有动态评价（支持隐私透视）。

请求参数

参数名	类型	必填	说明
action	string	是	get_event_detail
id	int	是	活动的 event_id
viewer_uid	int	否	判定是否可编辑、点赞状态
is_admin	int	否	1/0，为1时透视匿名身份

返回示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "event_info": {
      "event_id": 102,
      "name": "2023萤火虫动漫游戏嘉年华"
    },
    "models": {
      "official": [{"id": 1, "name": "星野奈奈"}],
      "ugc_captured": [{"id": 5, "name": "野生Coser小月"}]
    },
    "reviews": {
      "list": [
        {
          "id": 204,
          "content": "镜头感无敌！",
          "likes": {"count": 42, "has_liked": true},
          "tagged_model": {"id": 1, "name": "星野奈奈"},
          "author": {
            "uid": 10086,
            "name": "摄影老法师",
            "is_me": true,
            "is_anon_perspective": false
          }
        }
      ],
      "total_count": 1
    }
  }
}