Token 模块

Token 模块专注于 AI 模型调用中 input/output token 的用量追踪、平台定价管理和第三方市场价格对比，是计费模块的核心数据源。

10.1 用量仪表盘（核心看板）

总览仪表盘

GET /api/v1/tokens/usage/dashboard

{
  "code": 0,
  "data": {
    "today": {
      "input_tokens": 128000,
      "output_tokens": 64000,
      "total_tokens": 192000,
      "total_cost": "5.38",
      "request_count": 350
    },
    "this_month": {
      "input_tokens": 3200000,
      "output_tokens": 1600000,
      "total_tokens": 4800000,
      "total_cost": "134.40",
      "request_count": 8750
    },
    "trend": [
      { "date": "2024-01-01", "total_tokens": 180000, "total_cost": "5.04", "request_count": 320 },
      { "date": "2024-01-02", "total_tokens": 192000, "total_cost": "5.38", "request_count": 350 }
    ]
  }
}

按 API Key 统计

GET /api/v1/tokens/usage/by-apikey

{
  "code": 0,
  "data": {
    "items": [
      {
        "key_id": "key_01HX...",
        "key_name": "生产环境",
        "key_prefix": "sk-prod-****",
        "request_count": 5200,
        "input_tokens": 2100000,
        "output_tokens": 980000,
        "total_tokens": 3080000,
        "total_cost": "86.24",
        "last_used_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Top 10 模型用量排行

GET /api/v1/tokens/usage/top-models

{
  "code": 0,
  "data": {
    "period": "this_month",
    "items": [
      {
        "rank": 1,
        "model_id": "gpt-4o",
        "display_name": "GPT-4o",
        "provider_name": "OpenAI",
        "request_count": 3200,
        "input_tokens": 1500000,
        "output_tokens": 720000,
        "total_tokens": 2220000,
        "total_cost": "62.16",
        "avg_latency_ms": 1240
      }
    ]
  }
}

Top 10 用户用量排行（管理员）

GET /admin/v1/tokens/usage/top-users

实时用量（最近 60 分钟）

GET /api/v1/tokens/usage/realtime

{
  "code": 0,
  "data": {
    "items": [
      { "minute": "2024-01-01T12:00:00Z", "total_tokens": 3200, "request_count": 5 },
      { "minute": "2024-01-01T12:01:00Z", "total_tokens": 4800, "request_count": 8 }
    ]
  }
}

用量热力图

GET /api/v1/tokens/usage/heatmap

{
  "code": 0,
  "data": {
    "data": [
      { "weekday": "Monday", "hour": 10, "total_tokens": 45000, "level": 3 },
      { "weekday": "Monday", "hour": 11, "total_tokens": 89000, "level": 5 }
    ]
  }
}

level 范围 1-5，数值越高代表用量越高。

10.2 用量明细

总用量汇总

GET /api/v1/tokens/usage

用量明细列表

GET /api/v1/tokens/usage/detail

{
  "code": 0,
  "data": {
    "items": [
      {
        "request_id": "req_abc123",
        "model_id": "gpt-4o",
        "model_name": "GPT-4o",
        "api_key_id": "key_01HX...",
        "input_tokens": 512,
        "output_tokens": 256,
        "total_tokens": 768,
        "input_cost": "0.01434",
        "output_cost": "0.02150",
        "total_cost": "0.03584",
        "latency_ms": 1180,
        "currency": "CNY",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

每日用量趋势

GET /api/v1/tokens/usage/daily

月度用量汇总

GET /api/v1/tokens/usage/monthly

单次请求 Token 详情

GET /api/v1/tokens/usage/{request_id}

10.3 平台 Token 定价管理（管理员）

全量定价列表

GET /admin/v1/tokens/pricing

{
  "code": 0,
  "data": {
    "items": [
      {
        "pricing_id": "price_001",
        "model_id": "gpt-4o",
        "model_name": "GPT-4o",
        "currency": "CNY",
        "unit": "per_1k_tokens",
        "tiers": [
          { "membership_level": "free",    "input_price": "0.035", "output_price": "0.105" },
          { "membership_level": "basic",   "input_price": "0.028", "output_price": "0.084" },
          { "membership_level": "premium", "input_price": "0.021", "output_price": "0.063" }
        ],
        "effective_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

指定模型定价详情

GET /admin/v1/tokens/pricing/{model_id}

创建定价规则

POST /admin/v1/tokens/pricing

{
  "model_id": "claude-3-5-sonnet",
  "currency": "CNY",
  "unit": "per_1k_tokens",
  "tiers": [
    { "membership_level": "free",    "input_price": "0.045", "output_price": "0.135" },
    { "membership_level": "basic",   "input_price": "0.036", "output_price": "0.108" },
    { "membership_level": "premium", "input_price": "0.027", "output_price": "0.081" }
  ],
  "effective_at": "2024-02-01T00:00:00Z"
}

更新定价规则

PUT /admin/v1/tokens/pricing/{pricing_id}

删除定价规则

DELETE /admin/v1/tokens/pricing/{pricing_id}

定价历史变更记录

GET /admin/v1/tokens/pricing/history/{model_id}

10.4 第三方市场价格

市场价格列表

GET /api/v1/tokens/market-prices

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "mkt_001",
        "provider": "openai",
        "provider_name": "OpenAI",
        "model_name": "gpt-4o",
        "input_price": "0.0375",
        "output_price": "0.1125",
        "currency": "CNY",
        "source_url": "https://openai.com/pricing",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

添加第三方价格（管理员）

POST /admin/v1/tokens/market-prices

更新第三方价格（管理员）

PUT /admin/v1/tokens/market-prices/{id}

删除第三方价格（管理员）

DELETE /admin/v1/tokens/market-prices/{id}

10.5 价格对比分析

全模型价格对比

GET /api/v1/tokens/price-comparison

{
  "code": 0,
  "data": {
    "items": [
      {
        "model_id": "gpt-4o",
        "display_name": "GPT-4o",
        "platform_price": {
          "input": "0.028",
          "output": "0.084",
          "membership_level": "basic"
        },
        "market_prices": [
          {
            "provider": "openai",
            "input": "0.0375",
            "output": "0.1125",
            "savings_input": "25.3%",
            "savings_output": "25.3%"
          }
        ]
      }
    ]
  }
}

指定模型价格对比

GET /api/v1/tokens/price-comparison/{model_id}

10.6 费用预估

POST /api/v1/tokens/estimate

{
  "model_id": "gpt-4o",
  "input_tokens": 1000,
  "output_tokens": 500
}

响应：

{
  "code": 0,
  "data": {
    "model_id": "gpt-4o",
    "input_tokens": 1000,
    "output_tokens": 500,
    "input_cost": "0.028",
    "output_cost": "0.042",
    "total_cost": "0.070",
    "currency": "CNY",
    "applied_pricing": {
      "membership_level": "basic",
      "input_price": "0.028",
      "output_price": "0.084"
    }
  }
}