🎮 天堂2效率计算器 - API文档

📋 简介

本文档描述如何通过API上传Boss时间数据，适用于安卓模拟器自动扫描脚本。

脚本可以自动截取游戏屏幕，识别Boss击退时间，并通过API自动上传到服务器。

🔐 认证方式

所有API请求需要在Header中携带API Key：

x-api-key: YOUR_API_KEY

或者在Query参数中：

?api_key=YOUR_API_KEY
⚠️ 注意：API Key是敏感信息，请勿泄露。可在管理员后台重置。

🚀 API接口

POST/api/upload/boss

功能：上传单个Boss时间

请求参数

参数名 类型 必填 说明
username string 是 用户名（需在网站上已注册）
boss_name string 是 Boss名称
kill_time string 否 击退时间，格式：2026-07-03 14:30 或 2026年07月03日14时30分
respawn_time string 否 刷新时间（如果提供，会自动计算击退时间）
respawn_hours number 否 刷新间隔小时数（不提供则自动从Boss数据库查找）
alert_msg string 否（推荐） 倒计时提醒文本，如 "佩尔利斯出现前5分钟。"
服务器收到后会自动推送到用户所有推送渠道
10分钟内同一Boss不会重复推送
✅ 推荐用法：脚本识别到倒计时提示时，只需传 boss_name + alert_msg，无需时间字段

请求示例

示例1：上传击退时间（传统方式）
curl -X POST https://onizuka.cn/api/upload/boss \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "username": "testuser",
    "boss_name": "魔图拉",
    "kill_time": "2026-07-03 14:30",
    "respawn_hours": 4
  }'
示例2：倒计时提醒（自动推送，推荐）
curl -X POST https://onizuka.cn/api/upload/boss \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "username": "testuser",
    "boss_name": "佩尔利斯",
    "alert_msg": "佩尔利斯出现前5分钟。"
  }'

Python示例

import requests

url = "https://onizuka.cn/api/upload/boss"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}
data = {
    "username": "testuser",
    "boss_name": "魔图拉",
    "kill_time": "2026-07-03 14:30",
    "respawn_hours": 4
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

返回示例

{
  "ok": true,
  "updated": false,
  "timer": {
    "id": 1234567890,
    "user_id": 1,
    "boss_name": "魔图拉",
    "kill_time": "2026-07-03T14:30:00.000Z",
    "respawn_time": "2026-07-03T18:30:00.000Z",
    "respawn_hours": 4,
    "source": "manual",
    "notify_enabled": true,
    "notified": false
  }
}

POST/api/upload/boss/batch

功能：批量上传Boss时间（推荐，减少请求次数）

请求参数

参数名 类型 必填 说明
username string 是 用户名
bosses array 是 Boss数组，每个元素包含 boss_name, kill_time, respawn_time, respawn_hours

请求示例

curl -X POST https://onizuka.cn/api/upload/boss/batch \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "username": "testuser",
    "bosses": [
      {
        "boss_name": "魔图拉",
        "kill_time": "2026-07-03 14:30",
        "respawn_hours": 4
      },
      {
        "boss_name": "度图拉",
        "kill_time": "2026-07-03 15:00",
        "respawn_hours": 6
      }
    ]
  }'

返回示例

{
  "ok": true,
  "total": 2,
  "success": 2,
  "failed": 0,
  "results": [
    {"boss_name": "魔图拉", "updated": false},
    {"boss_name": "度图拉", "updated": true}
  ],
  "errors": []
}

⚠️ 错误码

HTTP状态码 说明
200 成功
400 请求参数错误（详见返回msg）
401 API Key无效或缺失
404 用户不存在
500 服务器内部错误

📝 时间格式说明

API支持多种时间格式：

🤖 脚本开发指南

✅ 推荐方案：使用批量上传接口 /api/upload/boss/batch

脚本逻辑建议：

  1. 截图游戏画面
  2. 使用OCR识别Boss名称和击退时间
  3. 整理成JSON数组
  4. 调用批量上传接口
  5. 检查返回结果，处理失败项

完整Python脚本示例

import requests
import time
from datetime import datetime

API_URL = "https://onizuka.cn/api/upload/boss/batch"
API_KEY = "YOUR_API_KEY"
USERNAME = "testuser"

def upload_bosses(boss_list):
    """上传Boss时间列表"""
    payload = {
        "username": USERNAME,
        "bosses": boss_list
    }
    headers = {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
    }

    try:
        resp = requests.post(API_URL, json=payload, headers=headers, timeout=10)
        result = resp.json()
        if result.get("ok"):
            print(f"✅ 上传成功：{result['success']}/{result['total']}")
            if result.get("errors"):
                for err in result["errors"]:
                    print(f"❌ 失败：{err}")
        else:
            print(f"❌ 上传失败：{result.get('error')}")
    except Exception as e:
        print(f"❌ 请求异常：{e}")

# 示例：模拟识别到的Boss数据
bosses = [
    {
        "boss_name": "魔图拉",
        "kill_time": datetime.now().strftime("%Y-%m-%d %H:%M"),
        "respawn_hours": 4
    }
]

upload_bosses(bosses)

📞 联系支持

如有问题，请联系管理员获取：