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

> 更新时间：2026-08-21

## 基础信息

- 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`：自动档，按模型和渠道健康度选择，并按最终成功档位结算。
- 档位功能分阶段上线；控制台显示的实时价格和可选范围为最终有效规则。

## 3. 渠道池

- OpenCode 1–19 已全部退役，调度器与配置均禁止调用。
- 当前仅开放经济档；实际扣费倍率以模型市场展示为准。
- `deepseek-v4-flash`：`selfdeploy-v4flash-01`（严格最多 300 并发）→ `chatgptpay-v4flash-01` → Ollama 007/008 → TR → SophNet → `xfyun-maas` → `deepseek-v4-flash-vision-exp`。
- `deepseek-v4-pro`：SophNet → TR → Ollama → `nb-02`。
- `glm-5.3`：保持原经济档路由不变。
- `kimi-k3`：SophNet → 已验证可用的 Ollama → `nb-01` → `nb-02`。
- 其他已上架 0.3x 模型：SophNet 首选，TR 与 Ollama 全局兜底。
- GPT 模型路由不变。

## 路由与流式行为

- 流式请求使用 SSE；客户端应持续读取直到 `[DONE]`。
- 若首选渠道不可用，系统按上述经济档顺序进行故障转移。

## 常见错误

| 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`


## 技术支持

- 微信：aaa3dpclub
- 邮箱：a18yuan@163.com
- 反馈时请提供请求 ID、发生时间、模型 ID 和错误码，不要发送完整 API Key 或敏感对话。