{
  "schema_version": "1.0",
  "updated_at": "2026-09-07",
  "service": {
    "name": "3DP TokenHub",
    "api_compatibility": "OpenAI Chat Completions",
    "base_url": "https://token.3dpclub.com/v1",
    "authentication": {
      "type": "bearer",
      "header": "Authorization: Bearer YOUR_API_KEY"
    }
  },
  "endpoints": [
    {"method": "POST", "path": "/chat/completions", "purpose": "创建聊天补全，支持流式响应"},
    {"method": "GET", "path": "/models", "purpose": "获取公开模型列表（含定价与档位，无需认证）"},
    {"method": "GET", "path": "/model-status", "purpose": "模型健康状态（15 分钟窗口，公开）"},
    {"method": "GET", "path": "/model-detail/{model_id}", "purpose": "单模型详情 + 各档位渠道统计（公开）"}
  ],
  "query_endpoints": [
    {"method": "GET", "path": "/v1/balance", "auth": "bearer", "purpose": "账户可用余额（CNY）", "params": {}, "fields": ["currency", "available", "user_id", "key_id", "key_prefix"]},
    {"method": "GET", "path": "/v1/transactions", "auth": "bearer", "purpose": "余额变动流水（充值/扣费/返利/赠送/调整/兑换）", "params": {"limit": "int，默认 50，最大 500", "offset": "int，默认 0", "type": "usage_deduct|referral_reward|redeem|signup_bonus|adjust", "start": "YYYY-MM-DD 或 ISO 时间（北京时间）", "end": "同 start"}, "fields": ["id", "type", "amount", "balance_after", "note", "created_at"]},
    {"method": "GET", "path": "/v1/usage-records", "auth": "bearer", "purpose": "每次 API 调用明细（含成功与失败）", "params": {"limit": "int", "offset": "int", "model": "按模型过滤", "status": "按 HTTP 状态码过滤", "start": "时间范围", "end": "时间范围"}, "fields": ["id", "model", "prompt_tokens", "completion_tokens", "cached_tokens", "cost", "status_code", "error_type", "ttft_ms", "tps", "created_at"]},
    {"method": "GET", "path": "/v1/consumption", "auth": "bearer", "purpose": "消费汇总（总量/按模型）+ 扣费明细", "params": {"limit": "int（仅影响明细 records）", "offset": "int", "start": "时间范围", "end": "时间范围"}, "fields": ["summary.total_charged", "summary.total_requests", "summary.by_model", "records"]}
  ],
  "query_auth_notes": [
    "账户接口需 Authorization: Bearer YOUR_API_KEY",
    "按账户维度（user_id）返回该账户下全部 API Key 的数据",
    "仅校验 Key 有效性，不设余额门槛（余额为 0 仍可查询）",
    "无效 Key 返回 401"
  ],
  "minimal_request": {
    "method": "POST",
    "url": "https://token.3dpclub.com/v1/chat/completions",
    "headers": {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    "body": {"model": "glm-5.2", "messages": [{"role": "user", "content": "你好"}], "stream": true}
  },
  "api_key_rules": [
    "完整 Key 只展示一次",
    "Key 应保存在服务端环境变量或密钥管理器中",
    "不要在前端、公开仓库、截图或日志中暴露 Key",
    "修改服务档位只影响后续新请求"
  ],
  "service_tiers": [
    {"id": "economy", "name": "经济档", "planned_multiplier": 0.2, "description": "价格优先"},
    {"id": "fast", "name": "快速档", "planned_multiplier": 0.4, "description": "优先低延迟渠道，首字 5 秒为服务目标而非绝对承诺"},
    {"id": "auto", "name": "自动档", "planned_multiplier": null, "description": "按模型和渠道健康度选择，按最终成功档位结算"}
  ],
  "routing": {
    "factors": ["model_capability", "channel_health", "priority", "ttft", "concurrency", "cooldown"],
    "stream_switching": "流式内容发送后不透明切换上游",
    "fallback": "高档位可在开始输出前按规则降级",
    "source_of_truth": "控制台模型市场中的模型、价格和实时状态"
  },
  "errors": [
    {"status": 400, "meaning": "参数或模型能力不兼容", "action": "检查模型 ID、tools、JSON 模式和 token 上限"},
    {"status": 401, "meaning": "Key 无效或已停用", "action": "检查 Bearer 鉴权和 Key 状态"},
    {"status": 402, "meaning": "余额不足", "action": "充值后重试"},
    {"status": 429, "meaning": "并发、RPM 或上游限流", "action": "指数退避并降低并发"},
    {"status": 503, "meaning": "渠道暂不可用或重试耗尽", "action": "保留请求 ID 和发生时间，稍后重试"}
  ],
  "troubleshooting_fields": ["request_id", "timestamp_with_timezone", "model_id", "http_status", "response_body", "stream", "client_version"],
  "links": {
    "documentation": "https://token.3dpclub.com/docs",
    "console": "https://token.3dpclub.com/panel",
    "security": "https://token.3dpclub.com/security",
    "markdown": "https://token.3dpclub.com/docs/ai.md",
    "json": "https://token.3dpclub.com/docs/ai.json"
  },
  "notice": "服务档位分阶段上线；控制台实时显示的价格与可选范围为最终有效规则。"
}