开发者文档 · TokenPower

⚡ 5 分钟快速开始

第 1 步：创建账号获取密钥（1 分钟）

访问注册页创建账号（自动获得 $1 体验额度）
控制台 → 令牌 → 添加令牌，复制 sk-xxxxxx

第 2 步：选择你的客户端或 SDK（4 分钟）

99% 用户都用以下客户端之一：点击下方选择，跳转到具体配置。

客户端	适合人群	配置难度
Claude Code	Claude Code 用户	⭐ 很简单（3 行环境变量）
Cursor	Cursor IDE 用户	⭐ 很简单（2 个配置项）
Cherry Studio	本地 GUI 应用用户	⭐ 很简单（填表单）
LobeChat	多模型聚合用户	⭐ 很简单（填表单）
Hermes Agent	本地 AI 代理用户	⭐ 很简单（编辑 YAML）

或者用 SDK 集成到代码：

SDK	模型库	Base URL
Python OpenAI	GPT / Claude / 其他	`https://api.tokenpower.app/v1`
Node.js OpenAI	GPT / Claude / 其他	`https://api.tokenpower.app/v1`
Anthropic SDK	Claude 系列	`https://api.tokenpower.app` （不要加 /v1）

第 3 步：验证（测试一次请求）

curl https://api.tokenpower.app/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

🔑 认证方式

所有请求都需要你的 API Key。获取方式：

登录控制台 → 令牌 → 添加令牌
复制 sk-xxxxx 格式的密钥

在 HTTP 请求中：

Authorization: Bearer sk-你的TokenPower密钥

在 SDK 中：直接在初始化时传入 api_key 参数（见下方各 SDK 示例）

🤖 Claude Code

最推荐用 Claude Code 的用户。三个环境变量搞定：

export ANTHROPIC_BASE_URL=https://api.tokenpower.app
export ANTHROPIC_API_KEY=sk-你的密钥
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

⚠️ 重要提示：

Base URL 是 https://api.tokenpower.app（不要加 /v1）
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 防止 Claude Code 自动启用某些实验性 beta 导致不兼容
如果需要使用 Claude beta 特性（Vision、Prompt Caching），删除第三行，见 Claude Beta 特性部分

🎯 Cursor

设置 → Models → Override OpenAI Base URL：

Base URL: https://api.tokenpower.app/v1
API Key:  sk-你的密钥

🍒 Cherry Studio

设置 → 模型服务 → 添加自定义服务：

提供商：OpenAI
API Key：sk-你的密钥
API 地址：https://api.tokenpower.app/v1

🤖 LobeChat

设置 → 语言模型 → OpenAI：

API Key：sk-你的密钥
API 代理地址：https://api.tokenpower.app/v1

🧠 Hermes Agent

Hermes 是一个本地 AI 代理。仅需改 ~/.hermes/config.yaml 一个文件的 4 行即可接入 TokenPower。

编辑 ~/.hermes/config.yaml

找到 model 字段，改成：

model:
  default: claude-opus-4-20250514
  provider: custom
  base_url: https://api.tokenpower.app/v1
  api_key: sk-你的TokenPower密钥

其他字段（providers, toolsets 等）保持不动。

验证

hermes chat -q "What is 1+1?" -Q

应该看到 Claude 的回复。

常见问题

401 Unauthorized → 检查 API Key 是否有效（TokenPower 后台删除了）
Model not found → 改成 TokenPower 支持的模型名（claude-opus-4-20250514 / claude-sonnet-4-6 等）
Connection refused → 检查 base_url 是否正确（生产用 https://api.tokenpower.app/v1，本地开发用 http://localhost:13000/v1）

🐍 Python SDK (OpenAI)

pip install openai

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.tokenpower.app/v1"
)

resp = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}]
)
print(resp.choices[0].message.content)

📗 Node.js SDK (OpenAI)

npm i openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-你的密钥',
  baseURL: 'https://api.tokenpower.app/v1',
});

const resp = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});

🧠 Anthropic SDK (Claude)

方式 1：环境变量（推荐）

export ANTHROPIC_API_KEY=sk-你的密钥
export ANTHROPIC_BASE_URL=https://api.tokenpower.app

python your_script.py

方式 2：代码中初始化

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-你的密钥",
    base_url="https://api.tokenpower.app"
)

msg = client.messages.create(
    model="claude-opus-4",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

⚠️ 重要：Base URL 不要加 /v1

# ✅ 正确
base_url="https://api.tokenpower.app"

# ❌ 错误
base_url="https://api.tokenpower.app/v1"

🔀 协议选择（重要）

TokenPower 同时支持 OpenAI、Anthropic、Gemini 三种协议，可跨协议互转。但原生协议匹配上游模型时最稳，能完整保留缓存 / 思考链 / 工具调用等高级特性。

SDK / 客户端	推荐路径	说明
Anthropic SDK / Claude Code	`/v1/messages`	Anthropic 原生
OpenAI SDK / Cursor / Cherry / LobeChat	`/v1/chat/completions`	OpenAI 兼容
Google AI SDK	`/v1beta/...`	Gemini 原生

原则：客户端协议 = 上游协议时最稳，不丢字段。跨协议调用支持基础对话和工具，但不保证 prompt caching、extended thinking 等独占特性。

Claude Beta 特性

Anthropic 定期发布 Beta 特性。使用时需在请求头添加 anthropic-beta。

Vision（图像理解）

支持状态：✅ 完全支持

from anthropic import Anthropic
import base64

client = Anthropic(api_key="sk-...", base_url="https://api.tokenpower.app")

# 读取本地图片
with open("image.jpg", "rb") as img_file:
    img_data = base64.standard_b64encode(img_file.read()).decode("utf-8")

msg = client.messages.create(
    model="claude-opus-4",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": img_data
                    }
                },
                {"type": "text", "text": "这是什么图片？"}
            ]
        }
    ]
)

Prompt Caching（缓存长文本）

支持状态：✅ 完全支持 | 缓存命中享受 90% 折扣

使用场景：重复查询同一份长文档（合同、代码库、论文等）

from anthropic import Anthropic

client = Anthropic(api_key="sk-...")

# 加载一份很长的文档
long_document = open("contract.txt").read()

msg = client.messages.create(
    model="claude-opus-4",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一个法律助手"
        },
        {
            "type": "text",
            "text": long_document,
            "cache_control": {"type": "ephemeral"}  # ← 标记为可缓存
        }
    ],
    messages=[{"role": "user", "content": "合同的第 3 条是什么？"}]
)

# 查看缓存命中统计
print(f"输入 tokens: " + f"{msg.usage.input_tokens}")
print(f"缓存读取: " + f"{msg.usage.cache_read_input_tokens}")  # 只算 10% 费用

File Upload（文件 API）

支持状态：✅ 支持 | 最大 20MB

上传文档后直接在消息中引用，无需手动切割。

更多 Beta 特性：Extended Thinking（长链条推理）、Batch API（异步批处理）等陆续推出。详见 Anthropic 官方文档。

✨ 功能支持矩阵

下表列出各种功能的支持状态。绿色 ✅ = 完全支持，黄色 ⚠️ = 部分支持或可能被禁用。

功能	支持状态	说明
流式输出（stream）	✅ 完全支持	所有模型和协议都支持
函数调用（Tool Use）	✅ 完全支持	OpenAI 和 Anthropic 协议都支持
Vision（图像理解）	✅ 完全支持	支持 base64 / URL 两种格式
Prompt Caching（缓存）	✅ 完全支持	Anthropic SDK；缓存命中 90% 折扣
File Upload（文件 API）	✅ 完全支持	Anthropic SDK；支持 PDF、文本、图片
Batch API（异步批处理）	⚠️ 测试中	仅 Anthropic SDK；小时级别返回
Web Search（联网）	❌ 不支持	模型端本身不支持
Code Execution（代码执行）	❌ 不支持	安全政策限制
文本转语音（TTS）	⚠️ 部分型号	仅某些模型；可能因用户等级被禁用

⚠️ 如果某个功能被禁用：通常是因为你的账户等级限制。联系客服或升级套餐可解除。某些 Beta 特性（如 Extended Thinking）可能需要主动开通。

🛣️ API 端点

Base URL: https://api.tokenpower.app/v1

端点	方法	说明
`/chat/completions`	POST	对话补全（OpenAI 兼容）
`/completions`	POST	文本补全
`/embeddings`	POST	向量嵌入
`/images/generations`	POST	图像生成 (DALL·E)
`/audio/transcriptions`	POST	语音转文字 (Whisper)
`/models`	GET	列出可用模型

Chat Completions 示例

{
  "model": "claude-opus-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is TokenPower?"}
  ],
  "stream": true,
  "temperature": 0.7
}

计费规则

单次费用 = (输入tokens × 输入单价 + 输出tokens × 输出单价) ÷ 1M

具体单价以控制台账单为准，支持 Anthropic Prompt Caching。

错误码

HTTP	含义	处理
401	密钥无效	检查 Authorization header
403	模型未授权	令牌设置中开启对应模型
402	余额不足	充值
429	触发限流	降低并发或升级套餐
500	上游错误	自动重试或联系客服
503	上游不可用	已自动切换备用渠道，可重试

FAQ

和官方 API 有什么区别？

OpenAI 兼容接口，多家厂商模型聚合在一个 Key 下，方便切换和统一计费。

会记录我的请求内容吗？

不会。我们只记录调用元数据（时间、模型、token 数）用于计费，不存储 prompt 和 response 正文。

支持流式输出吗？

支持，所有兼容 OpenAI 的 stream 参数都生效。

余额会过期吗？

永久有效，无月费。

能开发票吗？

充值满 ¥500 可开增值税普通发票，联系客服。

支持私有部署吗？

企业用户支持私有化方案，邮件咨询 [email protected]