{
  "schema_version": "1.0",
  "updated_at": "2026-10-02",
  "service": {
    "name": "3DP TokenHub",
    "api_compatibility": "OpenAI Chat Completions + Anthropic Messages",
    "base_url": "https://token.3dpclub.com/v1",
    "authentication": {
      "type": "bearer",
      "header": "Authorization: Bearer YOUR_API_KEY"
    }
  },
  "endpoints": [
    {"method": "POST", "path": "/chat/completions", "purpose": "创建聊天补全，支持流式响应"},
    {"method": "POST", "path": "/messages", "purpose": "Anthropic Messages 协议兼容端点"},
    {"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"
  ],
  "balance_monitoring": {
    "purpose": "把余额接入监控与告警系统（渠道余额监控）",
    "endpoint": "GET https://token.3dpclub.com/v1/balance",
    "auth": "Authorization: Bearer YOUR_API_KEY",
    "request_params": {},
    "charged": false,
    "scope": "按账户返回，该账户下全部 Key 共用一份余额",
    "response_example": {"currency": "CNY", "available": 128.75, "user_id": "u_1024", "key_id": "k_8f3a2c"},
    "value_field": "available",
    "value_field_note": "可用余额（元），监控取值使用该字段",
    "fields": [
      {"name": "currency", "type": "string", "desc": "币种，固定为 CNY"},
      {"name": "available", "type": "number", "desc": "可用余额（元），监控取值就用它"},
      {"name": "user_id", "type": "string", "desc": "账户标识"},
      {"name": "key_id", "type": "string", "desc": "本次调用所用 Key 标识"}
    ],
    "polling_advice": "建议 1~5 分钟轮询一次，不要高于每分钟 1 次；接口不计费但过高频率无意义",
    "combo": [
      {"goal": "当前余额、是否该充值", "endpoint": "GET /v1/balance"},
      {"goal": "余额变动原因（充值/扣费/返利）", "endpoint": "GET /v1/transactions"},
      {"goal": "每天/每模型烧了多少", "endpoint": "GET /v1/consumption"},
      {"goal": "单次请求明细（token、延迟、状态）", "endpoint": "GET /v1/usage-records"}
    ],
    "example_python": "import requests, time\nAPI_KEY='YOUR_API_KEY'\nURL='https://token.3dpclub.com/v1/balance'\nwhile True:\n    r=requests.get(URL, headers={'Authorization': f'Bearer {API_KEY}'}, timeout=10)\n    bal=float(r.json()['available'])\n    if bal < 20: print('⚠️ 余额偏低')\n    time.sleep(300)"
  },
  "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 并新建完成轮换；不要在前端、公开仓库、截图或日志中暴露 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": "服务档位分阶段上线；控制台实时显示的价格与可选范围为最终有效规则。"
}