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

> 更新时间：2026-10-02

## 基础信息

- API 类型：OpenAI Chat Completions 兼容，同时支持 Anthropic Messages 协议
- Base URL：`https://token.3dpclub.com/v1`
- Chat Completions：`POST /v1/chat/completions`
- Anthropic Messages：`POST /v1/messages`
- Models：`GET /v1/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 可在控制台「API Key」列表中点「查看」**随时再次查看与复制**，不会丢失。
3. 怀疑泄露时：删除旧 Key 并新建一个完成轮换；不要在前端代码、公开仓库、截图或日志中暴露 Key。
4. Key 的服务档位可以编辑；修改只影响保存后的新请求，无需重建 Key。
5. 早于「可再次查看」功能上线的历史 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 有效性，不设余额门槛。

## 渠道余额监控（重点）

**把余额接入监控 / 告警系统，只需一个接口。**

- 接口：`GET https://token.3dpclub.com/v1/balance`
- 认证：`Authorization: Bearer YOUR_API_KEY`
- 请求参数：无
- 计费：不产生费用，仅校验 Key 有效性
- 数据维度：按账户返回（该账户下全部 Key 共用一份余额）

### 请求

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

### 响应

```json
{
  "currency": "CNY",
  "available": 128.75,
  "user_id": "u_1024",
  "key_id": "k_8f3a2c"
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| currency | string | 币种，固定为 CNY |
| available | number | **可用余额（元）**，监控取值就用它 |
| user_id | string | 账户标识 |
| key_id | string | 本次调用所用 Key 标识 |

### 监控示例（Python）

```python
import requests, time
API_KEY = "YOUR_API_KEY"
URL = "https://token.3dpclub.com/v1/balance"

while True:
    r = requests.get(URL, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=10)
    bal = float(r.json()["available"])
    print("可用余额:", bal, "CNY")
    if bal < 20:
        print("⚠️ 余额偏低，请及时充值")
    time.sleep(300)  # 建议 1~5 分钟一次
```

### 组合用法

| 目标 | 接口 |
|---|---|
| 当前余额、是否该充值 | `GET /v1/balance` |
| 余额变动原因（充值/扣费/返利） | `GET /v1/transactions` |
| 每天/每模型烧了多少 | `GET /v1/consumption` |
| 单次请求明细（token、延迟、状态） | `GET /v1/usage-records` |

建议轮询间隔 1~5 分钟，不要高于每分钟 1 次。

### 余额
```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`