{
  "api": "whichllm-saas",
  "base_url": "https://whichllm.net",
  "format": "json",
  "cache": "Cache-Control max-age=60-600",
  "description": "whichllm-saas API - GPU/LLM 硬件排行榜与模型匹配查询服务。所有端点默认返回 JSON。",
  "version": "1.0.0",
  "auth": "大部分公共端点无需认证。管理端点（cron/*, seed）需 CRON_SECRET 或限制 POST。",
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/rankings",
      "description": "排行榜总览。支持分页、多字段筛选、多列排序，返回 D1 或 KV 来源的排行数据。",
      "parameters": {
        "page": {
          "type": "integer",
          "default": 1,
          "description": "页码，最小为 1"
        },
        "limit": {
          "type": "integer",
          "default": 50,
          "max": 100,
          "description": "每页条数"
        },
        "profile": {
          "type": "string",
          "default": "all",
          "description": "使用场景筛选：general / coding / vision / math / all"
        },
        "category": {
          "type": "string",
          "default": "all",
          "description": "硬件类别筛选：consumer / workstation / datacenter / all"
        },
        "search": {
          "type": "string",
          "default": "",
          "description": "GPU 名称关键词搜索（模糊匹配）"
        },
        "min_score": {
          "type": "float",
          "default": 0,
          "description": "最低分数过滤"
        },
        "vram_min": {
          "type": "integer",
          "default": 0,
          "description": "最小显存(GB)"
        },
        "vram_max": {
          "type": "integer",
          "default": 999,
          "description": "最大显存(GB)"
        },
        "sort": {
          "type": "string",
          "default": "r",
          "description": "排序列代号: g=gpu, v=vram_gb, c=category, p=profile, r=rank, m=model_id, s=score, sp=speed_tok_per_sec, lk=likes, dl=downloads"
        },
        "dir": {
          "type": "string",
          "default": "asc",
          "description": "排序方向: asc / desc（order 参数亦可作为别名）"
        },
        "order": {
          "type": "string",
          "default": "asc",
          "description": "同 dir，为兼容旧版保留"
        }
      },
      "response_example": {
        "rows": [
          {
            "g": "RTX 4090",
            "i": "rtx-4090",
            "c": "consumer",
            "v": 24,
            "p": "general",
            "r": 1,
            "m": "Llama-3-70B",
            "q": "Q4_K_M",
            "s": 92,
            "sp": 45.2,
            "vr": 18.5,
            "b": 70,
            "e": "direct",
            "lk": 1523,
            "dl": 45231
          }
        ],
        "total": 120,
        "page": 1,
        "limit": 50,
        "pages": 3,
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/rankings?page=1&limit=20&profile=general&category=consumer&sort=s&dir=desc&min_score=50&vram_min=8&vram_max=48'"
    },
    {
      "method": "GET",
      "path": "/api/rankings/nearby",
      "description": "VRAM 相近的 GPU 排名列表。给定 GPU 或分数范围，查找 VRAM 相近的 GPU 及其排行榜。",
      "parameters": {
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景: general / coding / vision / math"
        },
        "gpu_id": {
          "type": "string",
          "default": "",
          "description": "GPU ID，以此 GPU 的 VRAM 为中心查找相近卡片"
        },
        "min_score": {
          "type": "float",
          "default": 0,
          "description": "最低分数"
        },
        "max_score": {
          "type": "float",
          "default": 100,
          "description": "最高分数"
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "max": 50,
          "description": "返回条数"
        }
      },
      "response_example": {
        "profile": "general",
        "gpu_id": "rtx-4090",
        "score_range": [
          0,
          100
        ],
        "rows": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "vram_gb": 24,
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "params_b": 70
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/rankings/nearby?gpu_id=rtx-4090&profile=general&min_score=70&limit=10'"
    },
    {
      "method": "GET",
      "path": "/api/models",
      "description": "查询指定 GPU 上可运行的模型列表（按分数降序）。",
      "parameters": {
        "gpu": {
          "type": "string",
          "required": true,
          "description": "GPU 名称关键词（模糊匹配，如 '4090' 或 'RTX 4090'）"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景: general / coding / vision / math"
        },
        "limit": {
          "type": "integer",
          "default": 50,
          "max": 100,
          "description": "返回条数"
        }
      },
      "response_example": {
        "gpu": "4090",
        "profile": "general",
        "models": [
          {
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "vram_required_gb": 18.5,
            "params_b": 70,
            "evidence": "direct",
            "rank": 1,
            "profile": "general",
            "lk": 1523,
            "dl": 45231
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/models?gpu=RTX+4090&profile=general&limit=10'"
    },
    {
      "method": "GET",
      "path": "/api/models/[id]",
      "description": "查询指定模型的详细信息，包括在所有 GPU 上的运行表现。model_id 从 URL 路径中提取。",
      "parameters": {
        "model_id": {
          "type": "string",
          "required": true,
          "location": "path",
          "description": "模型 ID，如 Llama-3-70B，作为 URL 路径最后一段"
        }
      },
      "response_example": {
        "ok": true,
        "model_id": "Llama-3-70B",
        "likes": 1523,
        "downloads": 45231,
        "gpus": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "vram_gb": 24,
            "profile": "general",
            "rank": 1,
            "quant": "Q4_K_M",
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "vram_required_gb": 18.5
          }
        ]
      },
      "curl_example": "curl 'https://whichllm.net/api/models/Llama-3-70B'"
    },
    {
      "method": "GET",
      "path": "/api/models/related",
      "description": "查找与指定模型 VRAM 需求相近的替代模型（同一 profile 内 VRAM 相差 <= 4GB）。",
      "parameters": {
        "model_id": {
          "type": "string",
          "required": true,
          "description": "模型 ID，如 Llama-3-70B"
        }
      },
      "response_example": {
        "ok": true,
        "model_id": "Llama-3-70B",
        "related": [
          {
            "model_id": "Mistral-7B",
            "quant": "Q4_K_M",
            "score": 88,
            "vram_required_gb": 16,
            "params_b": 7,
            "profile": "general",
            "likes": 2341,
            "downloads": 89210
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/models/related?model_id=Llama-3-70B'"
    },
    {
      "method": "POST",
      "path": "/api/models/enrich",
      "description": "从 HuggingFace API 批量拉取模型元数据（likes/downloads），跳过 24h 内已检查的模型。管理端点。",
      "parameters": {
        "body": {
          "type": "object",
          "description": "无需请求体，直接 POST 空请求即可触发"
        }
      },
      "response_example": {
        "ok": true,
        "enriched": 15,
        "skipped": 120,
        "total": 135,
        "errors": []
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/models/enrich'"
    },
    {
      "method": "GET",
      "path": "/api/reverse",
      "description": "反向查询：给定模型名称，查找哪些 GPU 可以运行该模型及其得分。",
      "parameters": {
        "model": {
          "type": "string",
          "required": true,
          "description": "模型名称关键词（模糊匹配）"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景: general / coding / vision / math"
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "max": 50,
          "description": "返回条数"
        }
      },
      "response_example": {
        "model": "Llama",
        "profile": "general",
        "rows": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "vram_gb": 24,
            "rank": 1,
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "vram_required_gb": 18.5,
            "params_b": 70,
            "quant": "Q4_K_M",
            "evidence": "direct",
            "lk": 1523,
            "dl": 45231
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/reverse?model=Llama&profile=general&limit=5'"
    },
    {
      "method": "GET",
      "path": "/api/hot",
      "description": "热门排行卡片：返回每个 GPU 在 general profile 下排名第一（rank=1）的模型，按分数降序。",
      "parameters": {},
      "response_example": {
        "cards": [
          {
            "g": "RTX 4090",
            "i": "rtx-4090",
            "c": "consumer",
            "m": "Llama-3-70B",
            "q": "Q4_K_M",
            "s": 92,
            "e": "direct"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/hot'"
    },
    {
      "method": "GET",
      "path": "/api/kpi",
      "description": "关键指标总览：最高分、硬件数量、总配置数、总行数。",
      "parameters": {},
      "response_example": {
        "top_score": 99.5,
        "hardware_count": 45,
        "total_configs": 356,
        "row_count": 1680,
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/kpi'"
    },
    {
      "method": "GET",
      "path": "/api/autocomplete",
      "description": "硬件搜索自动补全。根据输入返回匹配的 GPU 名称列表。",
      "parameters": {
        "q": {
          "type": "string",
          "required": true,
          "description": "搜索关键词，至少 1 个字符"
        },
        "limit": {
          "type": "integer",
          "default": 10,
          "max": 20,
          "description": "最大返回建议数"
        }
      },
      "response_example": {
        "suggestions": [
          {
            "label": "NVIDIA GeForce RTX 4090",
            "value": "rtx-4090"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/autocomplete?q=rtx&limit=5'"
    },
    {
      "method": "GET",
      "path": "/api/search",
      "description": "全文搜索：按关键词搜索 GPU 名称和模型名称，返回匹配的排行记录。",
      "parameters": {
        "q": {
          "type": "string",
          "required": true,
          "description": "搜索关键词"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "max": 50,
          "description": "返回条数"
        }
      },
      "response_example": {
        "q": "4090",
        "profile": "general",
        "rows": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "vram_gb": 24,
            "profile": "general",
            "rank": 1,
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "vram_required_gb": 18.5,
            "params_b": 70,
            "evidence": "direct"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/search?q=4090&profile=general&limit=5'"
    },
    {
      "method": "POST",
      "path": "/api/search/log",
      "description": "记录用户搜索日志。使用内存缓冲批量写入 D1，并自动清理 30 天前的旧记录。",
      "parameters": {
        "body": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "required": true,
              "description": "搜索查询内容"
            },
            "profile": {
              "type": "string",
              "default": "general",
              "description": "使用场景"
            }
          }
        }
      },
      "response_example": {
        "ok": true
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/search/log' -H 'Content-Type: application/json' -d '{\"query\":\"RTX 4090\",\"profile\":\"general\"}'"
    },
    {
      "method": "GET",
      "path": "/api/trends",
      "description": "趋势数据：返回 30 天内的分数变化趋势和模型热度趋势。需要 D1 数据库支持。",
      "parameters": {},
      "response_example": {
        "ok": true,
        "score_trends": [
          {
            "model_id": "Llama-3-70B",
            "score": 92,
            "snapshot_date": "2026-06-01",
            "gpu_id": "rtx-4090",
            "profile": "general"
          }
        ],
        "popularity_trends": [
          {
            "model_id": "Llama-3-70B",
            "likes": 1523,
            "downloads": 45231,
            "snapshot_date": "2026-06-01"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/trends'"
    },
    {
      "method": "GET",
      "path": "/api/trend",
      "description": "单个 GPU 的分数变化趋势。需要 D1 数据库支持。",
      "parameters": {
        "gpu": {
          "type": "string",
          "required": true,
          "description": "GPU ID（如 rtx-4090）"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        },
        "days": {
          "type": "integer",
          "default": 30,
          "description": "回顾天数"
        }
      },
      "response_example": {
        "gpu": "rtx-4090",
        "profile": "general",
        "days": 30,
        "entries": [
          {
            "model_id": "Llama-3-70B",
            "score": 92,
            "snapshot_date": "2026-06-01"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/trend?gpu=rtx-4090&profile=general&days=30'"
    },
    {
      "method": "GET",
      "path": "/api/trending",
      "description": "热门搜索趋势：返回最近 7 天搜索次数最多的查询词。需要 D1 数据库支持。",
      "parameters": {},
      "response_example": {
        "trending": [
          {
            "query": "RTX 4090",
            "cnt": 42,
            "last_searched": "2026-06-12T10:00:00Z"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/trending'"
    },
    {
      "method": "GET",
      "path": "/api/meta",
      "description": "元数据：返回排行榜数据的最新更新时间。",
      "parameters": {},
      "response_example": {
        "updated_at": "2026-06-12T08:00:00Z",
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/meta'"
    },
    {
      "method": "POST",
      "path": "/api/detect",
      "description": "GPU 自动检测。接收用户提交的 GPU 名称/显存等信息，返回匹配结果、各 profile 下的推荐模型及升级路径。",
      "parameters": {
        "body": {
          "type": "object",
          "properties": {
            "gpu_name": {
              "type": "string",
              "required": true,
              "description": "GPU 名称（如 RTX 4090），也可用 gpu 字段"
            },
            "gpu": {
              "type": "string",
              "description": "同 gpu_name，二选一"
            },
            "vram_gb": {
              "type": "float",
              "default": 0,
              "description": "显存大小(GB)，用于 VRAM 回退匹配"
            },
            "ram_gb": {
              "type": "float",
              "default": 0,
              "description": "系统内存(GB)"
            },
            "os": {
              "type": "string",
              "default": "",
              "description": "操作系统信息"
            },
            "profile": {
              "type": "string",
              "default": "general",
              "description": "使用场景"
            }
          }
        }
      },
      "response_example": {
        "ok": true,
        "detected": {
          "gpu_name": "RTX 4090",
          "vram_gb": 24,
          "ram_gb": 32,
          "os": "Windows"
        },
        "matched": true,
        "gpu": "NVIDIA GeForce RTX 4090",
        "gpu_id": "rtx-4090",
        "category": "consumer",
        "vram_gb": 24,
        "profiles": {
          "general": [
            {
              "model": "Llama-3-70B",
              "rank": 1,
              "score": 92,
              "quant": "Q4_K_M",
              "speed": 45.2,
              "vram_required": 18.5,
              "params_b": 70,
              "likes": 1523,
              "downloads": 45231
            }
          ],
          "coding": [],
          "vision": [],
          "math": []
        },
        "upgrade_to": [
          {
            "gpu": "RTX 6000 Ada",
            "vram_gb": 48,
            "vram_delta": 24,
            "top_model": "Llama-3-405B",
            "score": 96
          }
        ],
        "vram_fallback": false,
        "manual_cmd": "pip install whichllm && whichllm",
        "manual_note": "如果自动检测不准确，请手动运行上述命令进行精确检测",
        "source": "d1"
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/detect' -H 'Content-Type: application/json' -d '{\"gpu_name\":\"RTX 4090\",\"vram_gb\":24,\"ram_gb\":32,\"os\":\"Windows\"}'"
    },
    {
      "method": "GET",
      "path": "/api/export",
      "description": "数据导出。支持 JSON、NDJSON、CSV 格式，可选字段和 profile/category 过滤。最大导出 10000 行。",
      "parameters": {
        "profile": {
          "type": "string",
          "default": "",
          "description": "按 profile 过滤（为空则不限制）"
        },
        "category": {
          "type": "string",
          "default": "",
          "description": "按 category 过滤（为空则不限制）"
        },
        "format": {
          "type": "string",
          "default": "json",
          "description": "输出格式: json / ndjson / csv"
        },
        "limit": {
          "type": "integer",
          "default": 5000,
          "max": 10000,
          "description": "最大返回行数"
        },
        "fields": {
          "type": "string",
          "default": "",
          "description": "逗号分隔的字段名列表（如 'gpu,model_id,score'），为空则返回所有字段"
        }
      },
      "response_example": {
        "rows": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "vram_gb": 24,
            "profile": "general",
            "rank": 1,
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92
          }
        ],
        "count": 5000,
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/export?format=json&profile=general&limit=100&fields=gpu,model_id,score'"
    },
    {
      "method": "GET",
      "path": "/api/leaderboard",
      "description": "排行榜（精简版）：返回指定 profile 下 rank=1 的 GPU 排行列表。",
      "parameters": {
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "max": 50,
          "description": "返回条数"
        }
      },
      "response_example": {
        "profile": "general",
        "entries": [
          {
            "gpu": "RTX 4090",
            "gpu_id": "rtx-4090",
            "category": "consumer",
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92,
            "vram_gb": 24,
            "params_b": 70,
            "evidence": "direct"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/leaderboard?profile=general&limit=10'"
    },
    {
      "method": "GET",
      "path": "/api/top-per-category",
      "description": "按类别分组的最优 GPU/模型组合。每个类别取 top 3 的 rank=1 模型。",
      "parameters": {
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        }
      },
      "response_example": {
        "profile": "general",
        "categories": {
          "consumer": [
            {
              "gpu": "RTX 4090",
              "gpu_id": "rtx-4090",
              "category": "consumer",
              "model_id": "Llama-3-70B",
              "quant": "Q4_K_M",
              "score": 92,
              "vram_gb": 24,
              "speed_tok_per_sec": 45.2,
              "evidence": "direct"
            }
          ],
          "workstation": [],
          "datacenter": []
        },
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/top-per-category?profile=general'"
    },
    {
      "method": "GET",
      "path": "/api/compare",
      "description": "对比两个 GPU 在指定 profile 下的模型表现。返回两个 GPU 上的模型列表。",
      "parameters": {
        "gpu1": {
          "type": "string",
          "required": true,
          "description": "第一个 GPU 名称关键词"
        },
        "gpu2": {
          "type": "string",
          "required": true,
          "description": "第二个 GPU 名称关键词"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        }
      },
      "response_example": {
        "gpu1": "RTX 4090",
        "gpu2": "RTX 3090",
        "profile": "general",
        "left": [
          {
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 92,
            "speed_tok_per_sec": 45.2,
            "vram_required_gb": 18.5,
            "params_b": 70,
            "evidence": "direct",
            "rank": 1
          }
        ],
        "right": [
          {
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "score": 75,
            "speed_tok_per_sec": 25.1,
            "vram_required_gb": 18.5,
            "params_b": 70,
            "evidence": "direct",
            "rank": 1
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/compare?gpu1=RTX+4090&gpu2=RTX+3090&profile=general'"
    },
    {
      "method": "GET",
      "path": "/api/similar",
      "description": "VRAM 相近的 GPU 推荐。给定 GPU ID，查找显存容量在 ±margin GB 范围内的其他 GPU。",
      "parameters": {
        "gpu": {
          "type": "string",
          "required": true,
          "description": "GPU ID（如 rtx-4090）"
        },
        "margin": {
          "type": "integer",
          "default": 4,
          "description": "VRAM 容差范围(GB)"
        }
      },
      "response_example": {
        "target": {
          "gpu": "NVIDIA GeForce RTX 4090",
          "gpu_id": "rtx-4090",
          "vram_gb": 24,
          "category": "consumer"
        },
        "similar": [
          {
            "gpu": "RTX 4080",
            "gpu_id": "rtx-4080",
            "vram_gb": 16,
            "category": "consumer"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/similar?gpu=rtx-4090&margin=8'"
    },
    {
      "method": "GET",
      "path": "/api/stats",
      "description": "全局统计概览：总数、平均分、最高/低分、平均速度/显存/参数量、按 profile 分布、top-10/bottom-10。",
      "parameters": {},
      "response_example": {
        "overview": {
          "total": 1680,
          "avg_score": 72.5,
          "min_score": 12,
          "max_score": 99.5,
          "avg_speed": 35.2,
          "avg_vram": 22.1,
          "avg_params": 45.3
        },
        "by_profile": [
          {
            "profile": "general",
            "cnt": 820,
            "avg_score": 75.2
          }
        ],
        "top_10": [
          {
            "gpu": "RTX 4090",
            "model_id": "Llama-3-70B",
            "score": 99.5
          }
        ],
        "bottom_10": [
          {
            "gpu": "GTX 1060",
            "model_id": "TinyLLaMA-1.1B",
            "score": 12
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/stats'"
    },
    {
      "method": "GET",
      "path": "/api/stats/summary",
      "description": "精简统计摘要：模型总数、GPU 总数、行数、平均分、最高分、最大下载量/点赞数。需要 D1。",
      "parameters": {},
      "response_example": {
        "ok": true,
        "model_count": 45,
        "gpu_count": 28,
        "total_rows": 1680,
        "avg_score": 72.5,
        "max_score": 99.5,
        "max_downloads": 89210,
        "max_likes": 2341,
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/stats/summary'"
    },
    {
      "method": "GET",
      "path": "/api/stats/monitor",
      "description": "KV 缓存命中率 + D1 查询延迟监控。返回当前 Worker 实例的 KV 命中/未命中/写入计数、D1 延迟百分位统计、db_stats 历史、实时数据量。",
      "parameters": {},
      "response_example": {
        "kv_cache": {
          "hits": 42,
          "misses": 3,
          "sets": 8,
          "hit_rate": "93.3%"
        },
        "d1_latency": {
          "samples": 50,
          "avg_ms": "12",
          "p50_ms": "8",
          "p95_ms": "35",
          "p99_ms": "120"
        },
        "db_stats_history": [],
        "realtime": {
          "rows": 3838,
          "gpus": 66,
          "models": 119,
          "avg_score": 46.8
        }
      },
      "curl_example": "curl 'https://whichllm.net/api/stats/monitor'"
    },
    {
      "method": "GET",
      "path": "/api/stats/distribution",
      "description": "数据分布统计：分数分布（10 分桶）、按 profile 分布、按 VRAM 区间分布。需要 D1。",
      "parameters": {},
      "response_example": {
        "score_distribution": [
          {
            "bucket": 80,
            "cnt": 45
          }
        ],
        "by_profile": [
          {
            "profile": "general",
            "cnt": 820,
            "avg_score": 75.2
          }
        ],
        "by_vram": [
          {
            "range": "16-24",
            "cnt": 320
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/stats/distribution'"
    },
    {
      "method": "GET",
      "path": "/api/categories",
      "description": "分类总览：返回每个类别的 GPU 数量、排行总数、平均分，以及总 GPU/模型/排行数和 profile 分布。需要 D1。",
      "parameters": {},
      "response_example": {
        "ok": true,
        "total_gpus": 45,
        "total_models": 120,
        "total_rankings": 1680,
        "categories": [
          {
            "name": "consumer",
            "gpu_count": 20,
            "total": 800,
            "avg_score": 74.5
          }
        ],
        "profile_distribution": [
          {
            "profile": "general",
            "count": 820
          }
        ]
      },
      "curl_example": "curl 'https://whichllm.net/api/categories'"
    },
    {
      "method": "GET",
      "path": "/api/changelog",
      "description": "最新更新日志：返回最近一条数据更新记录。",
      "parameters": {},
      "response_example": {
        "summary": "数据更新: 3 款新硬件, 2 个榜首变动",
        "details": "{\"new_gpus\":[\"RTX 5090\"],\"new_models\":[],\"score_changes\":[]}",
        "updated_at": "2026-06-12T08:00:00Z",
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/changelog'"
    },
    {
      "method": "GET",
      "path": "/api/history",
      "description": "更新日志历史列表：返回指定天数内的所有更新记录。需要 D1。",
      "parameters": {
        "days": {
          "type": "integer",
          "default": 7,
          "description": "回顾天数"
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "max": 50,
          "description": "返回条数"
        }
      },
      "response_example": {
        "entries": [
          {
            "id": 1,
            "summary": "数据更新: 3 款新硬件",
            "details": "{\"new_gpus\":[\"RTX 5090\"]}",
            "created_at": "2026-06-12T08:00:00Z"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/history?days=14&limit=10'"
    },
    {
      "method": "GET",
      "path": "/api/upgrade",
      "description": "升级路径推荐。给定当前 GPU，返回显存更高的 GPU 升级建议及各升级目标的最佳模型。",
      "parameters": {
        "gpu": {
          "type": "string",
          "required": true,
          "description": "当前 GPU 名称或 ID（如 rtx-4090 或 RTX 4090）"
        },
        "profile": {
          "type": "string",
          "default": "general",
          "description": "使用场景"
        }
      },
      "response_example": {
        "current": {
          "gpu": "NVIDIA GeForce RTX 4090",
          "gpu_id": "rtx-4090",
          "vram_gb": 24
        },
        "upgrade_to": [
          {
            "gpu": "RTX 6000 Ada",
            "gpu_id": "rtx-6000-ada",
            "vram_gb": 48,
            "vram_delta": 24,
            "top_model": "Llama-3-405B",
            "score": 96,
            "speed": 38.5
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/upgrade?gpu=rtx-4090&profile=general'"
    },
    {
      "method": "GET",
      "path": "/api/profile-compare",
      "description": "GPU 跨场景对比。返回指定 GPU 在 general/coding/vision/math 四个 profile 下的 top-3 模型表现。",
      "parameters": {
        "gpu": {
          "type": "string",
          "required": true,
          "description": "GPU 名称或 ID 关键词"
        }
      },
      "response_example": {
        "gpu": "NVIDIA GeForce RTX 4090",
        "gpu_id": "rtx-4090",
        "category": "consumer",
        "vram_gb": 24,
        "profiles": {
          "general": [
            {
              "m": "Llama-3-70B",
              "r": 1,
              "s": 92,
              "q": "Q4_K_M",
              "sp": 45.2
            }
          ],
          "coding": [
            {
              "m": "CodeLlama-34B",
              "r": 1,
              "s": 88,
              "q": "Q4_K_M",
              "sp": 42.1
            }
          ],
          "vision": [],
          "math": []
        },
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/profile-compare?gpu=rtx-4090'"
    },
    {
      "method": "GET",
      "path": "/api/vram/estimate",
      "description": "VRAM 用量估算。给定模型名称，返回各量化级别的显存占用估算。",
      "parameters": {
        "model": {
          "type": "string",
          "required": true,
          "description": "模型名称关键词"
        },
        "quant": {
          "type": "string",
          "default": "",
          "description": "量化方式过滤（如 Q4_K_M），不区分大小写"
        }
      },
      "response_example": {
        "model": "Llama-3-70B",
        "quant": "any",
        "estimates": [
          {
            "model_id": "Llama-3-70B",
            "quant": "Q4_K_M",
            "vram_gb": 18.5,
            "params_b": 70
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/vram/estimate?model=Llama-3-70B&quant=Q4_K_M'"
    },
    {
      "method": "GET",
      "path": "/api/all",
      "description": "所有原始数据。返回 rankings 表的全部行（不分页、不过滤），按 gpu/profile/rank 排序。数据量可能很大！",
      "parameters": {},
      "response_example": {
        "rows": [
          {
            "g": "RTX 4090",
            "i": "rtx-4090",
            "c": "consumer",
            "v": 24,
            "p": "general",
            "r": 1,
            "m": "Llama-3-70B",
            "q": "Q4_K_M",
            "s": 92,
            "sp": 45.2,
            "vr": 18.5,
            "b": 70,
            "e": "direct"
          }
        ],
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/all'"
    },
    {
      "method": "GET",
      "path": "/api/d1",
      "description": "D1 数据库诊断。返回数据库状态、各表行数、延迟统计、慢查询记录等。内部管理用。",
      "parameters": {},
      "response_example": {
        "status": {
          "d1": true,
          "kv": true
        },
        "tables": {
          "rankings": 1680,
          "hardware": 45,
          "changelog": 12,
          "snapshots": 5200,
          "search_log": 890
        },
        "last_updated": "2026-06-12T08:00:00Z",
        "latency_ms": {
          "p50": 8,
          "p95": 35,
          "samples": 5
        },
        "db_size_mb": 2.45,
        "slow_queries": [],
        "error_rate": "0.12%",
        "query_count": 4520,
        "kv_meta": {},
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/d1'"
    },
    {
      "method": "GET",
      "path": "/api/validate",
      "description": "数据完整性校验。检查空分数、空 evidence、重复行、空 gpu_id、分数越界等问题。需要 D1。",
      "parameters": {},
      "response_example": {
        "ok": true,
        "checks": {
          "null_scores": 0,
          "null_evidence": 5,
          "duplicate_rows": 0,
          "null_gpu_id": 0,
          "min_score": 12,
          "max_score": 99.5,
          "avg_score": 72.5,
          "out_of_range": 0,
          "total_rows": 1680,
          "error_pct": "0.30%"
        },
        "source": "d1"
      },
      "curl_example": "curl 'https://whichllm.net/api/validate'"
    },
    {
      "method": "GET",
      "path": "/api/docs",
      "description": "API 文档（当前端点）。返回描述所有公开端点的结构化 JSON。",
      "parameters": {},
      "response_example": {
        "api": "whichllm-saas",
        "base_url": "https://whichllm.net",
        "format": "json",
        "endpoints": [
          "共 39 个端点"
        ]
      },
      "curl_example": "curl 'https://whichllm.net/api/docs'"
    },
    {
      "method": "POST",
      "path": "/api/batch",
      "description": "批量 GPU 查询。一次请求查询多个 GPU 的模型排行数据。最多 10 个 GPU。",
      "parameters": {
        "body": {
          "type": "object",
          "required": [
            "gpus"
          ],
          "properties": {
            "gpus": {
              "type": "array",
              "required": true,
              "description": "GPU 名称/ID 数组，最多 10 个"
            },
            "profile": {
              "type": "string",
              "default": "general",
              "description": "使用场景"
            },
            "limit": {
              "type": "integer",
              "default": 3,
              "max": 10,
              "description": "每个 GPU 返回的模型数"
            }
          }
        }
      },
      "response_example": {
        "results": [
          {
            "query": "RTX 4090",
            "rows": [
              {
                "g": "RTX 4090",
                "i": "rtx-4090",
                "m": "Llama-3-70B",
                "s": 92
              }
            ],
            "count": 1
          }
        ],
        "profile": "general",
        "source": "d1"
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/batch' -H 'Content-Type: application/json' -d '{\"gpus\":[\"RTX 4090\",\"RTX 3090\"],\"profile\":\"general\",\"limit\":3}'"
    },
    {
      "method": "POST",
      "path": "/api/seed",
      "description": "从 KV 向 D1 数据库灌入数据。同步 hardware 表，插入 rankings 数据，生成 changelog 差异记录。管理端点。",
      "parameters": {
        "body": {
          "type": "object",
          "description": "无需请求体，直接 POST 空请求即可触发"
        }
      },
      "response_example": {
        "ok": true,
        "inserted": 1680,
        "hardware_synced": 45,
        "changelog": "diffed",
        "source": "d1",
        "enrichment": "call POST /api/models/enrich to fetch likes/downloads"
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/seed'"
    },
    {
      "method": "GET",
      "path": "/api/cron/enrich",
      "description": "定时任务：从 HuggingFace API 批量拉取模型元数据。GET 方式需提供 ?trigger=CRON_SECRET 参数。POST 方式任意调用（但需 D1）。",
      "parameters": {
        "trigger": {
          "type": "string",
          "required": false,
          "description": "CRON_SECRET，GET 请求时需要。默认值为 whichllm-cron-2024"
        }
      },
      "response_example": {
        "ok": true,
        "enriched": 15,
        "skipped": 120,
        "trends_recorded": 15,
        "total": 135,
        "errors": []
      },
      "curl_example": "curl 'https://whichllm.net/api/cron/enrich?trigger=whichllm-cron-2024'"
    },
    {
      "method": "POST",
      "path": "/api/cron/snapshot",
      "description": "定时快照：将当前 rankings 数据写入 snapshots 表，用于后续趋势分析。每次插入约 100 条一批。管理端点。",
      "parameters": {
        "body": {
          "type": "object",
          "description": "无需请求体，直接 POST 空请求即可触发"
        }
      },
      "response_example": {
        "ok": true,
        "inserted": 1680,
        "total": 1680,
        "source": "d1"
      },
      "curl_example": "curl -X POST 'https://whichllm.net/api/cron/snapshot'"
    }
  ]
}