> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 与 Anthropic SDK 接入指南

> 设置 SDK 的 Base URL 和认证，使用 Python、JavaScript 与 curl 调用 BetterToken 的三种文本 API，查看响应字段与排错方法。

OpenAI SDK 使用 Base URL `https://bettertoken.ai/v1`，Anthropic SDK 使用 `https://bettertoken.ai`。以下示例使用你的 BetterToken API Key，分别通过 Chat Completions、Responses 和 Messages 发送简短的文本请求。

## 选择 SDK 与 Base URL

| API | SDK | Base URL | HTTP 认证请求头 | 参考文档 |
| - | - | - | - | - |
| Chat Completions | OpenAI | `https://bettertoken.ai/v1` | `Authorization: Bearer YOUR_API_KEY` | [Chat Completions](/zh/api-reference/chat-completions.md) |
| Responses | OpenAI | `https://bettertoken.ai/v1` | `Authorization: Bearer YOUR_API_KEY` | [Responses](/zh/api-reference/responses.md) |
| Messages | Anthropic | `https://bettertoken.ai`，不带 `/v1` | `x-api-key: YOUR_API_KEY` | [Messages](/zh/api-reference/messages.md) |

SDK 会添加接口路径和认证请求头。Anthropic SDK 还会发送 API 版本请求头。如果你正在迁移已有代码，请参阅[协议对比](/zh/faq/concepts/openai-compatible-vs-anthropic-compatible.md)。

## 准备工作

先按[快速接入](/zh/quickstart.md)创建 BetterToken API Key 并充值。从[模型广场](https://bettertoken.ai/pricing)复制支持目标接口的 Model ID。发送请求前，替换下方的两个占位值。

在运行示例的终端中设置这些变量。本页 Shell 命令使用 macOS / Linux 语法：

```bash theme={null}
export BETTERTOKEN_API_KEY="YOUR_API_KEY"
export BETTERTOKEN_MODEL_ID="YOUR_MODEL_ID"
```

Python 用户请在项目虚拟环境中安装 SDK：

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
python -m pip install openai anthropic
```

JavaScript 用户请在项目中安装依赖，将每个示例保存为独立的 `.mjs` 文件，再用 `node` 运行：

```bash theme={null}
npm install openai @anthropic-ai/sdk
```

所有示例都从 `BETTERTOKEN_API_KEY` 读取密钥，并关闭 SDK 自动重试，避免一次测试在你不知情时发起多次请求。应用的重试策略请参阅[错误与限制](/zh/api-reference/errors.md#重试临时故障)。

## 调用 Chat Completions

用 `messages` 传入对话。文本请求成功后，从 `choices[0].message.content` 读取内容。

**Python**

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model=os.environ["BETTERTOKEN_MODEL_ID"],
    messages=[{"role": "user", "content": "Reply with one word: OK"}],
)
print(response.choices[0].message.content)
```

**JavaScript**

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  baseURL: "https://bettertoken.ai/v1",
  timeout: 120000,
  maxRetries: 0,
});
const response = await client.chat.completions.create({
  model: process.env.BETTERTOKEN_MODEL_ID,
  messages: [{ role: "user", content: "Reply with one word: OK" }],
});
console.log(response.choices[0].message.content);
```

**curl**

```bash theme={null}
curl --fail-with-body --max-time 120 "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$BETTERTOKEN_MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with one word: OK\"}]}"
```

## 调用 Responses

用 `input` 传入提示词。OpenAI SDK 提供便于读取文本的 `output_text` 属性；HTTP JSON 响应则包含 `output` 数组。请检查消息项及其中的文本内容，不要假设每个输出项都是文本。

**Python**

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.responses.create(
    model=os.environ["BETTERTOKEN_MODEL_ID"],
    input="Reply with one word: OK",
)
print(response.output_text)
```

**JavaScript**

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  baseURL: "https://bettertoken.ai/v1",
  timeout: 120000,
  maxRetries: 0,
});
const response = await client.responses.create({
  model: process.env.BETTERTOKEN_MODEL_ID,
  input: "Reply with one word: OK",
});
console.log(response.output_text);
```

**curl**

```bash theme={null}
curl --fail-with-body --max-time 120 "https://bettertoken.ai/v1/responses" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$BETTERTOKEN_MODEL_ID\",\"input\":\"Reply with one word: OK\"}"
```

## 调用 Messages

传入 `messages`，并设置必填的 `max_tokens`。这个简短文本请求的成功响应包含类似 `content[0].text` 的文本块。处理一般响应时，应遍历 `content`，只读取 `type: "text"` 的块。

**Python**

```python theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai",
    timeout=120.0,
    max_retries=0,
)
response = client.messages.create(
    model=os.environ["BETTERTOKEN_MODEL_ID"],
    max_tokens=256,
    messages=[{"role": "user", "content": "Reply with one word: OK"}],
)
for block in response.content:
    if block.type == "text":
        print(block.text)
```

**JavaScript**

```javascript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  baseURL: "https://bettertoken.ai",
  timeout: 120000,
  maxRetries: 0,
});
const response = await client.messages.create({
  model: process.env.BETTERTOKEN_MODEL_ID,
  max_tokens: 256,
  messages: [{ role: "user", content: "Reply with one word: OK" }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}
```

**curl**

```bash theme={null}
curl --fail-with-body --max-time 120 "https://bettertoken.ai/v1/messages" \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$BETTERTOKEN_MODEL_ID\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with one word: OK\"}]}"
```

## 列出可用模型

发送 `GET https://bettertoken.ai/v1/models`，使用 `Authorization: Bearer` 或 `x-api-key` 认证。成功时返回 HTTP `200`，顶层包含 `data`、`object` 和 `success` 字段。`data` 中的每个条目包含 `id`、`object`、`created`、`owned_by` 和 `supported_endpoint_types`。

**curl**

```bash theme={null}
curl --fail-with-body --max-time 120 "https://bettertoken.ai/v1/models" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY"
```

如需使用 `x-api-key`，将认证请求头替换为 `-H "x-api-key: $BETTERTOKEN_API_KEY"`。

**Python**

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
    timeout=120.0,
    max_retries=0,
)
for model in client.models.list():
    print(model.id)
```

将返回的 `id` 用作请求中的 `model`。不要依赖 `type` 或 `display_name`，这些字段并非每个条目都有。使用 `id` 选择模型，当前价格和完整模型说明请查看[模型广场](https://bettertoken.ai/pricing)。

## 常见错误

| 现象 | 检查与处理 |
| - | - |
| URL 错误或 `404` | OpenAI SDK 的 Base URL 带 `/v1`，Anthropic SDK 的不带。不要将完整接口路径追加到 SDK 的 Base URL。 |
| `401` 或缺少凭据 | 示例从 `BETTERTOKEN_API_KEY` 显式传入密钥。直接调用 OpenAI 接口使用 Bearer，直接调用 Messages 使用 `x-api-key`。 |
| 找不到模型 | 将 `YOUR_MODEL_ID` 替换为模型广场中准确、可用的 Model ID，并确认它支持所选接口。 |
| 请求仍发往旧地址 | 检查 SDK 参数和继承的变量，参阅[清除冲突的环境变量](/zh/best-practices.md#清除冲突的环境变量)。 |
| 文本为空或回答不完整 | 查看完整响应和停止原因，检查[输出 Token 上限](/zh/faq/model-calling/max-tokens.md)。 |

### 两种 SDK 可以共用一个 Key 吗？

可以。一个 BetterToken API Key 可调用所有可用模型。按各 SDK 的要求设置 Base URL 和请求格式即可。

### 如何添加流式输出、工具调用或结构化输出？

流式输出和工具调用的支持情况因模型而异。先用你的 Model ID 发送一个小请求，再按[流式输出与工具调用](/zh/guides/streaming-and-tool-calling.md)操作。JSON 校验和依赖模型支持的结构化输出请参阅[结构化 JSON 常见问题](/zh/faq/model-calling/structured-json-pydantic.md)。

## 相关文档

* [API 参考概览](/zh/api-reference/introduction.md)
* [支持的工具](/zh/ai-tools/overview.md)
* [API 错误、状态码与限流](/zh/api-reference/errors.md)
* [API Key 安全与超时配置](/zh/best-practices.md)
* [缓存计费规则](/zh/faq/service-assurance/cache-billing.md)

## 官方参考

* [OpenAI Python SDK](https://github.com/openai/openai-python)
* [OpenAI JavaScript SDK](https://github.com/openai/openai-node)
* [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python)
* [Anthropic JavaScript SDK](https://github.com/anthropics/anthropic-sdk-typescript)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.