BestAI Docs

外观

通用 SDK / API 接入指南 ​

适合使用 Python、Node.js、curl 或其他兼容客户端的用户。读完后，你可以选对协议和 Base URL，发出一次最小请求，并在使用记录中确认请求确实经过 BestAI。

先选协议 ​

BestAI 提供兼容接口，但不同工具的 Base URL 不完全相同。先按客户端选择：

客户端或场景Base URL主要接口
OpenAI SDK / 兼容工具https://api.bestai.chat/v1/chat/completions、/responses
Anthropic SDK / 兼容工具https://api.bestai.chat/v1/messages
Codex CLI / Apphttps://api.bestai.chatResponses，另需 wire_api = "responses"
Gemini 原生 REST 接口https://api.bestai.chat/v1beta/models、/models/{model}:generateContent
OpenAI Images APIhttps://api.bestai.chat/v1/images/generations、/images/edits

表中的 SDK 地址只适用于对应客户端；curl 要填写完整 URL。不要把 /v1/chat/completions 填进 OpenAI SDK 的 Base URL。Gemini 这一行描述 REST 路径，不代表任意 Google SDK 的 base_url 都应包含 /v1beta。

开始前准备 ​

  1. 在 API Keys 创建一把 Key，并选择支持目标协议的分组。
  2. 从控制台配置提示或工具当前配置中确定模型 ID。
  3. 确认账户余额或 Key 额度可用。

文档中的 sk-你的Key 和 MODEL_ID 都是占位符。真实值只放在本机环境变量中。

bash
export BESTAI_API_KEY="sk-你的Key"
export BESTAI_MODEL="工具当前配置中的模型 ID"

下面的 shell 命令适用于 Bash / Zsh / WSL。PowerShell 设置变量时使用 $env:BESTAI_API_KEY 和 $env:BESTAI_MODEL；请求部分可直接选用 Python 示例，不能原样粘贴 Bash 的换行和引号写法。每次换协议时，也要确认 Key 分组与模型都支持新协议。

准备 SDK 运行环境 ​

只安装你选用的 SDK。在自己的示例项目和 Python 虚拟环境中执行：

bash
python -m pip install openai

Anthropic 示例改用 python -m pip install anthropic。保存代码为 .py 后，用同一环境的 python 文件名.py 运行，确保运行解释器与安装依赖的解释器一致。

Node.js 示例在自己的项目目录运行 npm install openai，保存为 bestai-example.mjs，再运行 node bestai-example.mjs。下面的 import 写法需要 ES module；用 .mjs 可避免依赖项目的 type 设置。

请求失败时先看 HTTP 状态和错误正文。curl -sS 只控制输出方式，收到 HTTP 401/500 时不一定返回非零退出码；下面额外显示 HTTP 状态。不要为了调试打印带认证头的完整请求。

OpenAI 兼容接口 ​

curl：Chat Completions ​

bash
curl -sS "https://api.bestai.chat/v1/chat/completions" \
  -H "Authorization: Bearer $BESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BESTAI_MODEL"'",
    "messages": [{"role": "user", "content": "只回复：BestAI OpenAI ok"}]
  }' -w '\nHTTP %{http_code}\n'

curl：Responses ​

bash
curl -sS "https://api.bestai.chat/v1/responses" \
  -H "Authorization: Bearer $BESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BESTAI_MODEL"'",
    "input": "只回复：BestAI Responses ok"
  }' -w '\nHTTP %{http_code}\n'

Python：OpenAI SDK ​

python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bestai.chat/v1",
    api_key=os.environ["BESTAI_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["BESTAI_MODEL"],
    messages=[{"role": "user", "content": "只回复：BestAI SDK ok"}],
)
print(response.choices[0].message.content)

Responses SDK 使用同一 Base URL。保留上面的 import 与 client 初始化，将最后的调用替换为：

python
response = client.responses.create(
    model=os.environ["BESTAI_MODEL"],
    input="只回复：BestAI Responses SDK ok",
)
print(response.output_text)

Node.js：OpenAI SDK ​

javascript
import OpenAI from "openai";

if (!process.env.BESTAI_API_KEY || !process.env.BESTAI_MODEL) {
  throw new Error("请先设置 BESTAI_API_KEY 和 BESTAI_MODEL");
}

const client = new OpenAI({
  baseURL: "https://api.bestai.chat/v1",
  apiKey: process.env.BESTAI_API_KEY,
});

const response = await client.responses.create({
  model: process.env.BESTAI_MODEL,
  input: "只回复：BestAI Node SDK ok",
});

console.log(response.output_text);

Anthropic 兼容接口 ​

Anthropic SDK 的 Base URL 填根地址，不要加 /v1。SDK 会自行请求 /v1/messages。

curl：Messages ​

bash
curl -sS "https://api.bestai.chat/v1/messages" \
  -H "x-api-key: $BESTAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BESTAI_MODEL"'",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "只回复：BestAI Anthropic ok"}]
  }' -w '\nHTTP %{http_code}\n'

Python：Anthropic SDK ​

python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.bestai.chat",
    api_key=os.environ["BESTAI_API_KEY"],
)

message = client.messages.create(
    model=os.environ["BESTAI_MODEL"],
    max_tokens=256,
    messages=[{"role": "user", "content": "只回复：BestAI Anthropic SDK ok"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

Gemini 原生兼容接口 ​

只有分组明确提供 Gemini 时才使用这一组地址。模型 ID 和是否可用以控制台配置提示或工具当前配置为准。

bash
curl -sS "https://api.bestai.chat/v1beta/models" \
  -H "x-goog-api-key: $BESTAI_API_KEY" \
  -w '\nHTTP %{http_code}\n'

curl -sS "https://api.bestai.chat/v1beta/models/$BESTAI_MODEL:generateContent" \
  -H "x-goog-api-key: $BESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"只回复：BestAI Gemini ok"}]}]}' \
  -w '\nHTTP %{http_code}\n'

流式输出与图片 ​

OpenAI 和 Anthropic SDK 都支持流式输出，但事件格式和读取方式不同；只添加 stream 参数并不能让原来的非流式解析代码继续工作。先完成短请求验证，再参考Responses 流式完整示例，同时处理增量、完成和中断。Base URL 与认证方式沿用对应协议。

图片接口只对支持生图的分组开放。gpt-image-2、gemini-3.1-flash-image 和 gemini-3-pro-image 的完整请求体、响应字段以及 Base64/URL 保存方式，见生图接入指南。

OpenAI Images 用 size="1024x1024"、n=1；Gemini 用 imageConfig.imageSize="1K"，不添加 OpenAI 的 n 字段。先用简短提示词验证，再尝试大尺寸。模型、价格和分组能力以控制台当前显示为准。

接入完成标准 ​

一次接入同时满足下面两点才算完成：

  1. SDK 或工具收到短验证请求的模型回复。
  2. 使用记录 出现对应时间、模型和状态的请求。

暂时没有对应记录时，先刷新并检查日期、Key 与模型筛选，再确认当前 Provider 和地址。错误记录说明服务器记录了相应失败，但不等同于已计费用量；没有用量记录也不能单独证明请求未到站。详见核对一次请求。

常见错误 ​

现象先检查什么
401 / 403Key 是否完整、余额/额度是否可用、分组是否支持目标协议
404Base URL 是否多填了 endpoint，或把 /v1 用在了 Anthropic SDK
429区分额度耗尽、并发和短时限流，不立即循环重试
超时或流中断检查失败阶段和完成事件，保留部分输出
模型不存在确认模型 ID 与控制台配置提示一致，不要照抄旧示例
有回复但无使用记录先刷新、检查日期和筛选，再核对 Provider、地址和 Key
502 / 503保留时间、模型与脱敏错误正文，查看分组状态；避免自动反复重试产生额外请求

详细处理见常见问题和排障反馈模板。准备接入自己的项目时，继续阅读应用接入实践。

模型、协议与价格以当前分组和使用记录为准。

© 2026 BestAI