𝐗𝐀𝐈 𝐗𝐀𝐏𝐈

仪表盘 API

仪表盘 API 为用户端提供自助查询能力，包括账户状态、详细信息、用量统计、操作日志和新闻通知。前端控制台（/admin 与 /manage）主要通过这些端点渲染数据，同时也向第三方集成开放。

所有端点需携带 Authorization: Bearer sk-Xvs... 头。

基础 URL：https://api.xaixapi.com

—

端点概览

  • 用户状态：GET /dashboard/status
  • 用户详情：GET /dashboard/info
  • 用量账单：GET /dashboard/bill
  • 操作日志：GET /dashboard/logs
  • 新闻通知：GET /dashboard/news
  • 系统配置：GET /dashboard/conf
  • 模型清单：GET /dashboard/models

—

用户状态

获取当前用户的基本状态信息，适合快速查询。

端点： GET /dashboard/status

示例：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/status

响应：

{
  "object": "user_status",
  "id": 42,
  "dna": ".1.42.",
  "name": "prod-account",
  "email": "[email protected]",
  "alias": "生产环境",
  "public_key": "...",
  "balance": 450.25,
  "manage": true,  // 是否可访问 Manage 控制台
  "admin": true    // 是否可访问 Admin 控制台（仅主账户）
}

—

用户详情

获取详细的用户信息，包括余额明细、限制配置、用量统计和访问控制。

端点： GET /dashboard/info

示例：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/info

响应：

{
  "object": "user_info",
  "user": {
    "id": 42,
    "name": "prod-account",
    "email": "[email protected]",
    "alias": "生产环境",
    "level": 1,
    "gear": 1,
    "role": 1,
    "tier": 1,
    "factor": 1.0,
    "rates": 1.0,
    "dna": ".1.42.",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  },
  "balance": {
    "total": 450.25,
    "credits": [
      {
        "amount": 400.00,
        "expires_at": "2025-02-15T00:00:00Z"
      },
      {
        "amount": 50.25,
        "expires_at": "2025-03-01T00:00:00Z"
      }
    ]
  },
  "limits": {
    "hard_limit": 5000,
    "soft_limit": 4000,
    "auto_quota": 0,
    "rpm": 100,
    "rph": 3600,
    "rpd": 10000,
    "tpm": 200000,
    "tph": 6000000,
    "tpd": 50000000
  },
  "usage": {
    "today": {
      "requests": 150,
      "tokens": 450000,
      "cost": 12.50
    },
    "month": {
      "requests": 3500,
      "tokens": 12500000,
      "cost": 285.75
    }
  },
  "restrictions": {
    "allow_ips": ["192.168.1.0/24", "10.0.0.5"],
    "allow_models": ["gpt-4*", "claude-3*"],
    "resources": ["/v1/chat/completions", "/v1/embeddings"]
  },
  "model_limits": {
    "gpt-4": {
      "rpm": 30,
      "tpm": 90000
    },
    "claude-3-opus": {
      "rpm": 20,
      "tpm": 60000
    }
  }
}

—

用量账单

获取用量统计和账单信息，支持日期范围查询。

端点： GET /dashboard/bill

查询参数：

  • date 或 d - 指定日期（YYYY-MM-DD）
  • start 或 s - 开始日期
  • end 或 e - 结束日期
  • days - 过去 N 天（从今天算起）

费用说明：

  • 查询跨度 >30 天：计一次 API 费（0.01 美元）
  • 查询跨度 >365 天：自动截断至一年，并计额外费用（0.05 美元）

示例：

# 获取当月用量
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/bill

# 获取过去 30 天用量
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/dashboard/bill?days=30"

# 按日期范围查询
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/dashboard/bill?start=2025-01-01&end=2025-01-31"

响应：

{
  "object": "list",
  "data": [
    {
      "aggregation_timestamp": 1234567890,
      "n_requests": 1000,
      "n_context_tokens_total": 500000,
      "n_generated_tokens_total": 100000,
      "n_cached_tokens_total": 50000,
      "usage_details": {
        "gpt-4": {
          "requests": 100,
          "prompt": 50000,
          "completion": 10000,
          "cost": 3.5
        }
      }
    }
  ],
  "total_usage": {
    "requests": 10000,
    "prompt_tokens": 5000000,
    "completion_tokens": 1000000,
    "cached_tokens": 500000,
    "cost": 125.50
  }
}

—

操作日志

获取账户的操作日志记录，支持分页和过滤。

端点： GET /dashboard/logs

查询参数：

  • page - 页码（默认: 1）
  • size - 每页大小（默认: 24, 最大: 100）
  • action - 按操作类型筛选
  • target_id - 按目标 ID 筛选
  • status - 按状态筛选

示例：

# 获取最近日志
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/logs

# 分页获取日志
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/dashboard/logs?page=2&size=50"

# 筛选特定操作
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/dashboard/logs?action=add_user"

响应：

{
  "logs": [
    {
      "id": 123,
      "action": "add_user",
      "operator_id": 1,
      "target_id": 42,
      "details": "创建了用户，邮箱为: [email protected]",
      "ip_address": "192.168.1.100",
      "created_at": "2025-01-15 10:30:00",
      "status": "success"
    }
  ],
  "total": 150,
  "page": 1,
  "size": 24,
  "has_more": true
}

常见 action 类型：

  • add_user - 创建用户
  • update_user - 更新用户
  • delete_user - 删除用户
  • add_key - 添加密钥
  • update_key - 更新密钥
  • delete_key - 删除密钥
  • rotate_self - 密钥轮换
  • auto_config - 自动配置

—

新闻通知

获取系统新闻和用户通知。前端按需展示最新条目。

端点： GET /dashboard/news

示例：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/news

响应：

{
  "success": true,
  "system_news": [
    {
      "title": "系统更新通知",
      "content": "系统将于...",
      "created_at": "2025-01-15T10:00:00Z",
      "expires_at": "2025-01-22T10:00:00Z"
    }
  ],
  "user_news": [
    {
      "title": "账户余额提醒",
      "content": "您的账户余额不足...",
      "created_at": "2025-01-15T11:00:00Z",
      "expires_at": "2025-02-15T11:00:00Z"
    }
  ],
  "dna_news": [
    {
      "title": "团队通知",
      "content": "针对您所在团队的重要通知...",
      "created_at": "2025-01-15T12:00:00Z",
      "expires_at": "2025-02-15T12:00:00Z"
    }
  ]
}

新闻类型说明：

  • system_news - 系统级新闻（所有用户可见）
  • user_news - 用户级新闻（指定用户）
  • dna_news - DNA 组级新闻（指定 DNA 路径下的用户）

—

系统配置

获取全局关键阈值和配置参数。

端点： GET /dashboard/conf

示例：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/conf

响应：

{
  "UserMinBalance": 1.0,
  "UserApiBalance": 0.5,
  "SystemVersion": "v2.5.0",
  "Features": {
    "sign_enable": true,
    "safe_enable": true
  }
}

—

模型清单

获取当前系统内置/代理可用的模型清单。

端点： GET /dashboard/models

示例：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/models

响应：

{
  "models": [
    {
      "id": "gpt-4o",
      "provider": "openai",
      "context_window": 128000,
      "max_output_tokens": 16384
    },
    {
      "id": "claude-3-opus",
      "provider": "anthropic",
      "context_window": 200000,
      "max_output_tokens": 4096
    }
  ]
}

—

实时通道（可选）

实时通道用于上游实时能力的透明代理，鉴权与路由逻辑与常规代理一致。

端点： GET /v1/realtime（WebSocket 兼容）

说明： 此端点支持 WebSocket 协议，用于流式实时交互（如 OpenAI Realtime API）。

—

使用场景

场景 1：仪表盘首页

组合多个端点获取完整概览：

# 并行请求获取完整仪表盘数据
curl -H "Authorization: Bearer $API_KEY" https://api.xaixapi.com/dashboard/status &
curl -H "Authorization: Bearer $API_KEY" https://api.xaixapi.com/dashboard/info &
curl -H "Authorization: Bearer $API_KEY" "https://api.xaixapi.com/dashboard/bill?days=30" &
wait

场景 2：监控告警

定期检查余额和用量：

# 每小时检查账户状态
*/60 * * * * curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/dashboard/info | \
  jq '.balance.total' | \
  awk '{if($1<10) print "Low balance warning!"}'

场景 3：用量分析

获取详细的模型用量分析：

# 获取本月各模型用量
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/dashboard/bill" | \
  jq '.data[].usage_details'

—

最佳实践

  1. 缓存策略： 对于 /dashboard/status 和 /dashboard/info，建议客户端缓存 5-10 分钟
  2. 分页处理： 操作日志可能很多，请使用分页参数避免单次返回过多数据
  3. 日期范围： 查询用量时，建议日期范围不超过 90 天以获得最佳性能
  4. 错误处理： 所有端点都可能返回 401 Unauthorized，请检查密钥有效性
  5. 新闻轮询： 建议每 30 分钟轮询一次新闻端点，避免过于频繁
  6. 成本控制： 频繁查询长时间范围的账单会产生额外费用，请合理设置查询周期
← 访问控制 (ACL)
云服务 XAI Control 上手 →