# 3DP TokenHub 接入文档（AI 可读版）

> 更新时间：2026-09-07

## 基础信息

- API 类型：OpenAI Chat Completions 兼容接口
- Base URL：`https://token.3dpclub.com/v1`
- Chat Completions：`POST /chat/completions`
- Models：`GET /models`
- 鉴权：`Authorization: Bearer YOUR_API_KEY`
- Content-Type：`application/json`

## 最小请求

```bash
curl https://token.3dpclub.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"glm-5.2","messages":[{"role":"user","content":"你好"}],"stream":true}'
```

## Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://token.3dpclub.com/v1",
)
response = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "你好"}],
)
```

## API Key

1. 在控制台的“API Key”页面创建 Key。
2. 完整 Key 只展示一次，应保存在服务端环境变量或密钥管理器中。
3. 不要在前端代码、公开仓库、截图或日志中暴露 Key。
4. Key 的服务档位可以编辑；修改只影响保存后的新请求。

## 服务档位

- `economy`：经济档，规划倍率 `0.2x`，价格优先。
- `fast`：快速档，规划倍率 `0.4x`，优先低延迟渠道，首字 5 秒是服务目标而非绝对承诺。
- `auto`：自动档，按模型和渠道健康度选择，并按最终成功档位结算。
- 档位功能分阶段上线；控制台显示的实时价格和可选范围为最终有效规则。

## 路由与流式行为

- 路由考虑模型能力、渠道健康度、优先级、TTFT、并发和冷却状态。
- 流式内容一旦发送给客户端，不会透明切换上游。
- 高档位可在开始输出前按规则降级。
- 模型 ID、价格和实时状态以控制台“模型市场”为准。

## 查询接口

账户数据查询需 `Authorization: Bearer YOUR_API_KEY`；模型查询接口公开无鉴权。

| 接口 | 认证 | 用途 |
|---|---|---|
| GET /v1/balance | Bearer | 账户可用余额 |
| GET /v1/transactions | Bearer | 余额变动流水（充值/扣费/返利/赠送/调整/兑换） |
| GET /v1/usage-records | Bearer | 每次 API 调用明细 |
| GET /v1/consumption | Bearer | 消费汇总 + 扣费明细 |
| GET /v1/models | 公开 | 模型列表与定价 |
| GET /v1/model-status | 公开 | 模型健康状态（15 分钟窗口） |
| GET /v1/model-detail/{id} | 公开 | 单模型详情 + 各档位渠道统计 |

账户接口按「账户维度」返回该账户下全部 API Key 的数据；仅校验 Key 有效性，不设余额门槛。

### 余额
```bash
curl https://token.3dpclub.com/v1/balance -H "Authorization: Bearer YOUR_API_KEY"
```

### 账单流水
参数：limit(≤500)、offset、type(usage_deduct/referral_reward/redeem/signup_bonus/adjust)、start/end(北京时间)。
```bash
curl "https://token.3dpclub.com/v1/transactions?limit=20&type=usage_deduct" -H "Authorization: Bearer YOUR_API_KEY"
```
返回字段：id、type、amount(负数为扣费)、balance_after、note、created_at。

### 使用记录
参数：limit、offset、model、status(HTTP 状态码)、start/end。
```bash
curl "https://token.3dpclub.com/v1/usage-records?limit=20&status=200" -H "Authorization: Bearer YOUR_API_KEY"
```
返回字段：id、model、prompt_tokens、completion_tokens、cached_tokens、cost、status_code、error_type、ttft_ms、tps、created_at。

### 消费记录
参数：limit、offset、start/end。
```bash
curl "https://token.3dpclub.com/v1/consumption?limit=20" -H "Authorization: Bearer YOUR_API_KEY"
```
返回：summary(total_charged、total_requests、by_model) + records(扣费明细)。

## 常见错误

| HTTP | 含义 | 处理 |
|---|---|---|
| 400 | 参数或模型能力不兼容 | 检查模型 ID、tools、JSON 模式、token 上限 |
| 401 | Key 无效或已停用 | 检查 Bearer 鉴权和 Key 状态 |
| 402 | 余额不足 | 充值后重试 |
| 429 | 并发、RPM 或上游限流 | 指数退避并降低并发 |
| 503 | 渠道暂不可用或重试耗尽 | 保留请求 ID 和时间，稍后重试 |

## 排障时应收集

- 请求 ID
- 请求时间及时区
- 模型 ID
- HTTP 状态码和响应体
- 是否使用 `stream=true`
- 客户端和 SDK 版本

## 相关入口

- 人类可读文档：`https://token.3dpclub.com/docs`
- 控制台：`https://token.3dpclub.com/panel`
- 安全说明：`https://token.3dpclub.com/security`
- Markdown：`https://token.3dpclub.com/docs/ai.md`
- JSON：`https://token.3dpclub.com/docs/ai.json`