独家合作CubenceAI 中转平台立减 20%访问

Claude Code Hub

参考文档

Server Actions API

Claude Code Hub 提供了完整的 REST API，基于 Next.js Server Actions 自动生成 OpenAPI 3.1.0 规范文档。所有管理操作均通过统一的 API 层暴露，支持 Swagger UI 和 Scalar UI 两种交互式文档界面。

API 设计理念

CCH 的 API 采用 Server Actions + OpenAPI 架构：所有业务逻辑封装在 Server Actions 中，通过 @hono/zod-openapi 自动生成 REST 端点和 API 文档。这种设计确保了类型安全和文档自动同步。

API 文档访问

CCH 提供三种方式访问 API 文档：

访问方式地址说明
Scalar UI (推荐)/api/actions/scalar现代化交互界面，支持深色模式
Swagger UI/api/actions/docs经典 Swagger 界面
OpenAPI JSON/api/actions/openapi.json原始 OpenAPI 规范文件

生产环境配置

建议配置 APP_URL 环境变量，确保 OpenAPI 文档中的 servers 地址正确指向您的部署域名。

认证方式

Admin Token 认证

所有管理 API 需要管理员权限，通过 Cookie 进行身份验证：

  1. 访问 Web UI 登录页面
  2. 输入 ADMIN_TOKEN 环境变量中配置的令牌
  3. 登录成功后，服务器设置 HTTP-only Cookie
  4. 后续请求自动携带 Cookie 进行认证

权限级别

角色权限范围
admin完整系统管理权限，可访问所有 API
user仅能查看和管理自己的数据（密钥、统计等）

响应格式

所有 API 响应遵循统一格式：

// 成功响应
{
  "ok": true,
  "data": { ... }
}

// 错误响应
{
  "ok": false,
  "error": "错误消息",
  "errorCode": "ERROR_CODE"  // 可选，用于国际化
}

HTTP 状态码

状态码含义
200操作成功
400请求错误（参数验证失败或业务逻辑错误）
401未认证（需要登录）
403权限不足
500服务器内部错误

用户管理 API

用户管理相关的 CRUD 操作和限额查询。

API 端点列表

端点方法说明权限
/api/actions/users/getUsersPOST获取用户列表admin
/api/actions/users/addUserPOST创建新用户admin
/api/actions/users/editUserPOST编辑用户信息admin
/api/actions/users/removeUserPOST删除用户admin
/api/actions/users/getUserLimitUsagePOST获取用户限额使用情况admin/self

创建用户

POST /api/actions/users/addUser
Content-Type: application/json

{
  "name": "developer1",
  "note": "开发团队成员",
  "providerGroup": "default",
  "rpm": 60,
  "dailyQuota": 100,
  "limit5hUsd": 10,
  "limitWeeklyUsd": 50,
  "limitMonthlyUsd": 200,
  "limitConcurrentSessions": 5
}

响应示例：

{
  "ok": true
}

自动创建密钥

创建用户时会自动生成一个名为 default 的 API 密钥。

编辑用户

POST /api/actions/users/editUser
Content-Type: application/json

{
  "userId": 1,
  "name": "developer1-updated",
  "rpm": 120,
  "dailyQuota": 200
}

获取用户限额使用情况

POST /api/actions/users/getUserLimitUsage
Content-Type: application/json

{
  "userId": 1
}

响应示例：

{
  "ok": true,
  "data": {
    "rpm": {
      "current": 0,
      "limit": 60,
      "window": "per_minute"
    },
    "dailyCost": {
      "current": 15.5,
      "limit": 100,
      "resetAt": "2024-01-02T00:00:00.000Z"
    }
  }
}

密钥管理 API

API 密钥的创建、编辑、删除和限额查询。

API 端点列表

端点方法说明权限
/api/actions/keys/getKeysPOST获取用户的密钥列表admin/self
/api/actions/keys/addKeyPOST创建新密钥admin/self
/api/actions/keys/editKeyPOST编辑密钥信息admin/self
/api/actions/keys/removeKeyPOST删除密钥admin/self
/api/actions/keys/getKeyLimitUsagePOST获取密钥限额使用情况admin/self

创建密钥

POST /api/actions/keys/addKey
Content-Type: application/json

{
  "userId": 1,
  "name": "production-key",
  "expiresAt": "2025-12-31",
  "canLoginWebUi": false,
  "limit5hUsd": 5,
  "limitWeeklyUsd": 30,
  "limitMonthlyUsd": 100,
  "limitConcurrentSessions": 3
}

响应示例：

{
  "ok": true,
  "data": {
    "generatedKey": "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "name": "production-key"
  }
}

密钥安全

生成的密钥只会返回一次，请妥善保存。密钥在数据库中以 SHA-256 哈希形式存储。

获取密钥限额使用情况

POST /api/actions/keys/getKeyLimitUsage
Content-Type: application/json

{
  "keyId": 1
}

响应示例：

{
  "ok": true,
  "data": {
    "cost5h": {
      "current": 2.5,
      "limit": 5,
      "resetAt": "2024-01-01T05:00:00.000Z"
    },
    "costDaily": {
      "current": 8.0,
      "limit": 20,
      "resetAt": "2024-01-02T00:00:00.000Z"
    },
    "costWeekly": {
      "current": 25.0,
      "limit": 30,
      "resetAt": "2024-01-08T00:00:00.000Z"
    },
    "costMonthly": {
      "current": 80.0,
      "limit": 100,
      "resetAt": "2024-02-01T00:00:00.000Z"
    },
    "concurrentSessions": {
      "current": 2,
      "limit": 3
    }
  }
}

供应商管理 API

供应商的 CRUD 操作、健康状态监控和熔断器管理。

API 端点列表

端点方法说明权限
/api/actions/providers/getProvidersPOST获取供应商列表admin
/api/actions/providers/addProviderPOST创建新供应商admin
/api/actions/providers/editProviderPOST编辑供应商信息admin
/api/actions/providers/removeProviderPOST删除供应商admin
/api/actions/providers/getProvidersHealthStatusPOST获取供应商健康状态admin
/api/actions/providers/resetProviderCircuitPOST重置熔断器状态admin
/api/actions/providers/getProviderLimitUsagePOST获取供应商限额使用情况admin

创建供应商

POST /api/actions/providers/addProvider
Content-Type: application/json

{
  "name": "Anthropic Official",
  "url": "https://api.anthropic.com",
  "key": "sk-ant-xxxxx",
  "is_enabled": true,
  "weight": 100,
  "priority": 1,
  "cost_multiplier": 1.0,
  "provider_type": "claude",
  "group_tag": "official",
  "limit_5h_usd": 50,
  "limit_daily_usd": 100,
  "circuit_breaker_failure_threshold": 5,
  "circuit_breaker_open_duration": 1800000,
  "first_byte_timeout_streaming_ms": 30000,
  "streaming_idle_timeout_ms": 60000,
  "request_timeout_non_streaming_ms": 120000
}

获取供应商健康状态

POST /api/actions/providers/getProvidersHealthStatus

响应示例：

{
  "ok": true,
  "data": [
    {
      "providerId": 1,
      "providerName": "Anthropic Official",
      "state": "CLOSED",
      "failureCount": 0,
      "successCount": 150,
      "lastFailureTime": null,
      "lastSuccessTime": "2024-01-01T12:00:00.000Z"
    },
    {
      "providerId": 2,
      "providerName": "Backup Provider",
      "state": "OPEN",
      "failureCount": 5,
      "successCount": 10,
      "lastFailureTime": "2024-01-01T11:55:00.000Z",
      "openUntil": "2024-01-01T12:25:00.000Z"
    }
  ]
}

重置熔断器

POST /api/actions/providers/resetProviderCircuit
Content-Type: application/json

{
  "providerId": 2
}

统计分析 API

使用统计数据查询，支持多种时间范围和维度。

API 端点列表

端点方法说明权限
/api/actions/statistics/getUserStatisticsPOST获取用户统计数据admin/user
/api/actions/overview/getOverviewDataPOST获取首页概览数据admin/user

获取用户统计数据

POST /api/actions/statistics/getUserStatistics
Content-Type: application/json

{
  "timeRange": "day",
  "userId": 1
}

时间范围选项：

值说明
hour最近 1 小时
day最近 24 小时
week最近 7 天
month最近 30 天

响应示例：

{
  "ok": true,
  "data": {
    "chartData": [
      {
        "date": "2024-01-01T00:00:00.000Z",
        "user-1_cost": 5.5,
        "user-1_calls": 120
      }
    ],
    "users": [
      {
        "id": 1,
        "name": "developer1",
        "dataKey": "user-1"
      }
    ],
    "timeRange": "day",
    "resolution": "hour",
    "mode": "users"
  }
}

获取首页概览数据

POST /api/actions/overview/getOverviewData

响应示例：

{
  "ok": true,
  "data": {
    "concurrentSessions": 5,
    "todayRequests": 1500,
    "todayCost": 45.5,
    "avgResponseTime": 2500,
    "todayErrorRate": 0.5
  }
}

使用日志 API

请求日志查询和筛选。

API 端点列表

端点方法说明权限
/api/actions/usage-logs/getUsageLogsPOST获取使用日志admin/user
/api/actions/usage-logs/getModelListPOST获取日志中的模型列表admin/user
/api/actions/usage-logs/getStatusCodeListPOST获取日志中的状态码列表admin/user

获取使用日志

POST /api/actions/usage-logs/getUsageLogs
Content-Type: application/json

{
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-01-02T00:00:00.000Z",
  "model": "claude-sonnet-4-20250514",
  "statusCode": 200,
  "pageSize": 50,
  "page": 1
}

响应包含字段：

  • sessionId - Session ID
  • userId / userName - 用户信息
  • providerId / providerName - 供应商信息
  • model - 使用的模型
  • inputTokens / outputTokens - Token 统计
  • costUsd - 成本（美元）
  • durationMs - 响应时间（毫秒）
  • statusCode - HTTP 状态码
  • createdAt - 请求时间

Session 管理 API

活跃 Session 监控和详情查询。

API 端点列表

端点方法说明权限
/api/actions/active-sessions/getActiveSessionsPOST获取活跃 Session 列表admin/user
/api/actions/active-sessions/getSessionDetailsPOST获取 Session 详情admin/user
/api/actions/active-sessions/getSessionMessagesPOST获取 Session 消息内容admin/user

获取活跃 Session

POST /api/actions/active-sessions/getActiveSessions

响应示例：

{
  "ok": true,
  "data": [
    {
      "sessionId": "sess_abc123",
      "userName": "developer1",
      "userId": 1,
      "keyId": 1,
      "keyName": "default",
      "providerId": 1,
      "providerName": "Anthropic Official",
      "model": "claude-sonnet-4-20250514",
      "apiType": "chat",
      "startTime": 1704067200000,
      "inputTokens": 5000,
      "outputTokens": 2000,
      "totalTokens": 7000,
      "costUsd": 0.05,
      "requestCount": 10,
      "durationMs": 25000
    }
  ]
}

获取 Session 详情

POST /api/actions/active-sessions/getSessionDetails
Content-Type: application/json

{
  "sessionId": "sess_abc123"
}

Messages 存储

只有当 STORE_SESSION_MESSAGES=true 时，才能获取 Session 的完整消息内容。该功能会增加 Redis 内存使用，且消息可能包含敏感信息。

敏感词管理 API

敏感词过滤规则的 CRUD 操作。

API 端点列表

端点方法说明权限
/api/actions/sensitive-words/listSensitiveWordsPOST获取敏感词列表admin
/api/actions/sensitive-words/createSensitiveWordActionPOST创建敏感词admin
/api/actions/sensitive-words/updateSensitiveWordActionPOST更新敏感词admin
/api/actions/sensitive-words/deleteSensitiveWordActionPOST删除敏感词admin
/api/actions/sensitive-words/refreshCacheActionPOST刷新敏感词缓存admin
/api/actions/sensitive-words/getCacheStatsPOST获取缓存统计admin

创建敏感词

POST /api/actions/sensitive-words/createSensitiveWordAction
Content-Type: application/json

{
  "word": "敏感内容",
  "matchType": "contains",
  "description": "禁止包含此内容"
}

匹配类型：

值说明
contains包含匹配
exact精确匹配
regex正则表达式匹配

错误规则 API

错误分类和处理规则管理（通过 Web UI 管理，未暴露为 REST API）。

错误规则功能包括：

  • 模式匹配：支持 contains、exact、regex 三种匹配方式
  • 错误分类：prompt_limit、content_filter、pdf_limit、thinking_error、parameter_error、invalid_request、cache_limit
  • 响应覆写：自定义错误响应体和状态码
  • ReDoS 防护：自动检测危险的正则表达式

模型价格 API

模型价格表管理和同步。

API 端点列表

端点方法说明权限
/api/actions/model-prices/getModelPricesPOST获取所有模型价格admin
/api/actions/model-prices/uploadPriceTablePOST上传价格表admin
/api/actions/model-prices/syncLiteLLMPricesPOST同步 LiteLLM 价格表admin
/api/actions/model-prices/getAvailableModelsByProviderTypePOST获取可用模型列表admin
/api/actions/model-prices/hasPriceTablePOST检查是否有价格表all

同步 LiteLLM 价格表

POST /api/actions/model-prices/syncLiteLLMPrices

响应示例：

{
  "ok": true,
  "data": {
    "added": ["gpt-4o-2024-08-06", "claude-3-5-sonnet-20241022"],
    "updated": ["claude-sonnet-4-20250514"],
    "unchanged": ["gpt-4", "gpt-3.5-turbo"],
    "failed": [],
    "total": 150
  }
}

上传自定义价格表

POST /api/actions/model-prices/uploadPriceTable
Content-Type: application/json

{
  "jsonContent": "{\"custom-model\": {\"mode\": \"chat\", \"input_cost_per_token\": 0.00001, \"output_cost_per_token\": 0.00003}}"
}

系统配置 API

系统级配置管理。

API 端点列表

端点方法说明权限
/api/actions/system-config/fetchSystemSettingsPOST获取系统设置admin
/api/actions/system-config/saveSystemSettingsPOST保存系统设置admin

保存系统设置

POST /api/actions/system-config/saveSystemSettings
Content-Type: application/json

{
  "siteTitle": "My CCH Instance",
  "allowGlobalUsageView": false,
  "currencyDisplay": "USD",
  "enableAutoCleanup": true,
  "cleanupRetentionDays": 30,
  "enableClientVersionCheck": true
}

通知管理 API

Webhook 通知配置和测试。

API 端点列表

端点方法说明权限
/api/actions/notifications/getNotificationSettingsActionPOST获取通知设置admin
/api/actions/notifications/updateNotificationSettingsActionPOST更新通知设置admin
/api/actions/notifications/testWebhookActionPOST测试 Webhookadmin

测试 Webhook

POST /api/actions/notifications/testWebhookAction
Content-Type: application/json

{
  "webhookUrl": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
}

SSRF 防护

Webhook URL 会进行 SSRF 安全检查，禁止访问内部网络地址（localhost、私有 IP 等）。

健康检查端点

GET /api/actions/health

响应示例：

{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "version": "1.0.0"
}

错误处理最佳实践

处理认证错误

const response = await fetch('/api/actions/users/getUsers', {
  method: 'POST',
  credentials: 'include'  // 重要：携带 Cookie
});

if (response.status === 401) {
  // 重定向到登录页面
  window.location.href = '/login';
}

处理业务错误

const result = await response.json();

if (!result.ok) {
  // 显示错误消息
  toast.error(result.error);

  // 可选：根据 errorCode 进行特殊处理
  if (result.errorCode === 'PERMISSION_DENIED') {
    // 权限不足的特殊处理
  }
}

常见错误码

错误码含义
UNAUTHORIZED未登录
PERMISSION_DENIED权限不足
NOT_FOUND资源不存在
INVALID_FORMAT参数格式错误
CREATE_FAILED创建操作失败
UPDATE_FAILED更新操作失败
DELETE_FAILED删除操作失败
OPERATION_FAILED操作失败（通用）

相关链接

Cubence - AI 中转平台
独家合作

Cubence · AI 服务中转平台

为 Claude Code、Codex、Gemini 等 AI 工具提供稳定高效的中转服务

专属优惠码
DING113CCH
-20%
立即访问
Previous
Redis 架构
Next
数据库 Schema