鉴权与密钥

在控制台 → API 密钥创建密钥。创建时选择的分组决定这把密钥可调用的模型集合与计费价格（见「模型与定价」页），可同时设置额度上限。

三种协议的密钥传递方式：

# OpenAI 协议
Authorization: Bearer sk-xxxx

# Anthropic 协议
x-api-key: sk-xxxx
anthropic-version: 2023-06-01

# Gemini 原生协议
x-goog-api-key: sk-xxxx

同一把密钥在三种协议下通用。密钥仅在创建时完整展示，请妥善保存；泄露后在控制台删除并重建即可，历史用量不受影响。

Chat Completions

POST /v1/chat/completions，与 OpenAI 官方协议完全一致。网关上的所有模型（含 claude、gemini、deepseek 等）都可以通过这一个端点调用，协议转换由网关完成。

curl https://api.tokenliquid.cc/v1/chat/completions \
  -H "Authorization: Bearer $TL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024
  }'

常用参数

响应结构与 OpenAI 一致：choices[0].message.content 为回复内容，usage 含 prompt / completion tokens，计费依据即此字段。

Anthropic Messages

POST /v1/messages，与 Anthropic 官方协议一致。Claude Code、官方 SDK 等 Anthropic 生态工具可直接接入——base_url 填 https://api.tokenliquid.cc（不带 /v1）。

import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["TL_KEY"],
    base_url="https://api.tokenliquid.cc",
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)

Claude Code 接入：设置环境变量 ANTHROPIC_BASE_URL=https://api.tokenliquid.cc 与 ANTHROPIC_AUTH_TOKEN=你的密钥 即可。注意 max_tokens 为该协议必填字段；密钥需选择包含 claude 模型的分组（cc- 系列）。

Gemini 原生协议

POST /v1beta/models/{model}:generateContent，与 Google AI Studio 协议一致，官方 google-genai SDK 可直接指向网关。

curl "https://api.tokenliquid.cc/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $TL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "你好"}]}],
    "generationConfig": {"maxOutputTokens": 1024}
  }'

流式版本使用 :streamGenerateContent?alt=sse。gemini 系列模型同样可以走 OpenAI 协议（/v1/chat/completions）调用，两种方式计费一致，按团队现有 SDK 选择即可。

流式响应

三种协议均支持流式输出，网关原样转发上游的 SSE 事件流：

单请求超时上限 180 秒（含流式全程），足以覆盖长输出与深度思考模型。流式请求同样按 usage 中的实际 tokens 计费，用量明细在控制台日志逐条可查。

限流与重试

网关内建容错，对调用方透明：上游异常时自动重试最多 2 次并切换可用通道，持续故障的通道会被自动下线。

客户端侧建议：

错误码

错误以对应协议的标准结构返回（OpenAI 协议为 {"error": {...}}）。常见错误：

失败的请求不产生消费。排查问题时，控制台日志中的 request id 与每次响应携带的 id 一一对应。