API Docs - TokenLink

四大优势

① 兼容双协议（OpenAI + Anthropic）　② 缓存命中省钱（cached_tokens）　③ 成本归因（x-cost-center）　④ 多 Key 池隔离配额

快速开始

平台提供完全兼容 OpenAI 与 Anthropic 的接口，可使用任意 OpenAI 官方 SDK 直接接入。只需 5 步：注册账号 → 创建 API Key → 设置 baseURL → 发送首个请求 → 在控制台查看用量与账单。

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOKENLINK_API_KEY || 'tl-xxxxxxxxxxxxxxxx',
  baseURL: 'https://www.tokenlink.pro/v1'   // OpenAI 兼容
});

const response = await client.chat.completions.create({
  model: 'deepseek-v4-pro',
  messages: [{ role: 'user', content: '你好！' }]
});
console.log(response.choices[0].message.content);

认证方式

所有 API 请求都需在 Header 中携带您的 API Key（Bearer 模式）。Key 以 tl- 前缀开头，在控制台「API Keys」中创建与管理（创建时仅展示一次，系统以 SHA256 哈希加密存储）。

Authorization: Bearer tl-xxxxxxxxxxxxxxxx

支持一账号创建多个 Key（多 Key 池），可分别配置 key_type、rate_limit_rpm/tpm、daily_token_budget，用于区分业务线、隔离配额与成本归因。

Base URL 与兼容协议

对外统一域名 https://www.tokenlink.pro，提供三组入口：

协议	Base URL	适用 SDK
OpenAI 兼容	`https://www.tokenlink.pro/v1`	OpenAI / LangChain / OpenAI 生态
Anthropic 原生	`https://www.tokenlink.pro/v1`	Anthropic SDK / Claude Code
全路径直连	`https://www.tokenlink.pro/v1/chat/completions`	curl / 任意 HTTP 客户端

对话接口（OpenAI 兼容）

POST /v1/chat/completions

curl https://www.tokenlink.pro/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "你是专业的中文助手"},
      {"role": "user", "content": "用一句话解释什么是大模型 Token 聚合"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

响应（OpenAI 风格，含 tokenlink 扩展元数据 _tokenlink）：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "deepseek-v4-pro",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "Token 聚合平台通过统一接口接入多家大模型，按 Token 计量计费。"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 19, "completion_tokens": 13, "total_tokens": 32, "cached_tokens": 12},
  "_tokenlink": {"call_id": "tl-call-xxx", "supplier": "deepseek", "cost": 0.000123, "latency_ms": 890, "cache_hit": false, "billing": {"source": "quota", "charged": 0.000123}}
}

_tokenlink 为扩展元数据（成本、延迟、供应商、调用 ID），不影响 OpenAI 兼容性，可放心使用。

Anthropic 原生接口

POST /v1/messages　这是平台差异化优势，Anthropic SDK / Claude Code 可零改造接入。支持 model / system / messages / max_tokens / temperature / top_p / stream，content 支持 block 数组（tool_use / tool_result）。

curl https://www.tokenlink.pro/v1/messages \
  -H "Authorization: Bearer $TOKENLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "system": "You are a helpful assistant.",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 512
  }'

流式输出（SSE）

传 "stream": true，响应为 text/event-stream。每行 data: <JSON chunk>，以 data: [DONE] 结束。推荐传 stream_options: {"include_usage": true} 在最后一个 chunk 获取 usage。

curl -N https://www.tokenlink.pro/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-max", "messages": [{"role": "user", "content": "写一首关于春天的短诗"}], "stream": true, "stream_options": {"include_usage": true}}'

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"你好"},"index":0}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":19,"completion_tokens":13,"total_tokens":32}}
data: [DONE]

模型列表

GET /v1/models　返回所有可用模型，owned_by 为上游供应商代码。也可在控制台「模型广场」查看模型与价格。

curl https://www.tokenlink.pro/v1/models \
  -H "Authorization: Bearer $TOKENLINK_API_KEY"

{"object":"list","data":[{"id":"deepseek-v4-pro","object":"model","created":1768899826,"owned_by":"deepseek"}]}

其它能力

平台同时提供：

POST /v1/completions　文本补全（OpenAI 兼容）
POST /v1/embeddings　向量嵌入
POST /v1/images/generations　图像生成（OpenAI 兼容）
POST /v1/batches　Batch 批量接口（半价透传，头 x-supplier 指定上游）

参数说明

参数	类型	必填	说明
model	string	是	模型 ID，如 deepseek-v4-pro、qwen-max、glm-4-plus、kimi-k2
messages	array	是	对话消息列表，含 role 与 content；OpenAI 用 system 角色，Anthropic 用顶层 system
temperature	number	否	采样温度，范围 0-2，默认 1
top_p	number	否	核采样，范围 0-1，默认 1
max_tokens	number	否	最大输出 Token 数
stop	string/array	否	停止序列
stream	boolean	否	是否流式，默认 false
stream_options	object	否	如 {"include_usage": true}
response_format	object	否	如 {"type": "json_object"}
tools	array	否	工具调用（function calling）
user	string	否	业务用户 ID，可就近归因

多模态：content 支持 image_url（base64 或 URL）。

错误码表

HTTP	error.type	说明	建议处理
400	invalid_request_error	model 或 messages 缺失/非法	检查必填参数
401	invalid_request_error	API Key 无效/被停用	校验 Key；到控制台重新生成
402	billing_error	余额不足 / 超套餐用量	充值或升级配额
429	rate_limit_error	触发限流/RPM/TPM/日预算/熔断	按 retry_after 退避重试
500	server_error	网关内部错误	重试；持续则联系支持
502	server_error	上游供应商失败	自动重试或降级
503	server_error	供应商不可用	联系支持
504	server_error	请求超时（60s）	降低复杂度或重试

{"error": {"message": "Rate limit exceeded", "type": "rate_limit_error", "retry_after": 30}}

限流与配额

限流按 Key 维度：rate_limit_rpm / rate_limit_tpm / daily_limit / concurrent_limit。超限返回 429 并携带 retry_after。每日 Token 预算 daily_token_budget 超限后触发暂停/降级（economy 路由）。可在控制台「API Keys」查看配额并申请提升。

计费与用量

计费口径为 prompt_tokens + completion_tokens；输入命中缓存按 cached_tokens 计（享上游折扣，省钱卖点）。通过非流式 usage 或流式 stream_options.include_usage 读取。响应 _tokenlink.cost 透传本次成本，_tokenlink.billing 标示计费来源（套餐/按量/积分）。

多语言 SDK 与 FAQ

Node.js

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: 'tl-xxx', baseURL: 'https://www.tokenlink.pro/v1' });
const res = await client.chat.completions.create({ model: 'deepseek-v4-pro', messages: [{role:'user',content:'你好'}] });
console.log(res.choices[0].message.content, res.usage);

Python

from openai import OpenAI
client = OpenAI(api_key="tl-xxx", base_url="https://www.tokenlink.pro/v1")
resp = client.chat.completions.create(model="deepseek-v4-pro", messages=[{"role":"user","content":"你好"}])
print(resp.choices[0].message.content, resp.usage)

每 Key 限流维度：rpm / tpm / daily / concurrent；成本归因头：x-cost-center、x-session-id、x-agent-code。

常见问题（FAQ）

问题	处理
401 未授权	校验 API Key 是否有效、是否停用
429 限流	按 retry_after 退避重试或提升配额
模型不存在	先调 /v1/models 查看可用模型 ID
余额不足	控制台充值或升级套餐
SSE 断流	客户端可断点重连（按 id 续传）
中文乱码	确保请求与响应均使用 UTF-8 编码

开发者文档