TOKEN BOX API

快速开始

使用一个 OpenAI 兼容的接口，接入多种 AI 模型。几分钟内完成配置并发出第一条请求。

基础地址
https://tokenbox.cloud/v1
所有 API 路径都相对于这个地址。请将 API Key 保存在服务端环境变量中，不要写入浏览器代码或提交到代码仓库。

身份验证

在控制台创建 API Key，并在每次请求中使用 Bearer Token 认证：

Authorization: Bearer YOUR_TOKENBOX_API_KEY

推荐将密钥保存为环境变量：

export TOKENBOX_API_KEY="sk-your-key"

查询模型

调用模型列表接口获取当前账户可用的模型 ID。请始终使用返回结果中的准确名称。

GET https://tokenbox.cloud/v1/models

curl https://tokenbox.cloud/v1/models \
  -H "Authorization: Bearer $TOKENBOX_API_KEY"

发送对话请求

Chat Completions 接口接受消息数组，并返回模型生成的回复。

POST https://tokenbox.cloud/v1/chat/completions

curl https://tokenbox.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {"role": "system", "content": "你是一个简洁、准确的助手。"},
      {"role": "user", "content": "请用一句话介绍 Token Box"}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

消息角色

字段	说明
`system`	设定助手行为和回答边界。
`user`	来自用户的提问或任务。
`assistant`	历史助手消息，可用于多轮对话上下文。

流式响应

将 stream 设置为 true 后，服务会通过 SSE 持续返回增量内容，适合聊天界面实时展示。

curl https://tokenbox.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"model":"YOUR_MODEL_NAME","stream":true,"messages":[{"role":"user","content":"写一段简短的产品介绍"}]}'

客户端应逐行处理 data: 事件，并在收到 data: [DONE] 后关闭连接。

SDK 示例

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKENBOX_API_KEY",
    base_url="https://tokenbox.cloud/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

JavaScript / Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENBOX_API_KEY,
  baseURL: "https://tokenbox.cloud/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_NAME",
  messages: [{ role: "user", content: "你好" }],
});
console.log(response.choices[0].message.content);

错误处理

状态	常见原因	处理方式
401	密钥无效或缺少 Bearer 前缀	检查 API Key 和请求头。
404	模型或路径不存在	先调用 `/models` 核对模型 ID。
429	请求频率或额度受限	使用指数退避重试，并检查账户额度。
5xx	网关或上游模型暂时不可用	记录 request id，稍后重试。

生产环境建议记录 HTTP 状态码和响应中的 request id，但不要记录 API Key 或完整用户隐私内容。

需要帮助？发送邮件至 tokenbox88@outlook.com。