通用 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 / App	https://api.bestai.chat	Responses，另需 wire_api = "responses"
Gemini 原生兼容接口	https://api.bestai.chat/v1beta	/models、{model}:generateContent
OpenAI Images API	https://api.bestai.chat/v1	/images/generations、/images/edits

普通的 Base URL 字段只填表中的地址。不要把完整 endpoint 填进去，例如不要把 /v1/chat/completions 填进 OpenAI SDK 的 Base URL。

开始前准备

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

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

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

OpenAI 兼容接口

curl：Chat Completions

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"}]
  }'

curl：Responses

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"
  }'

Python：OpenAI SDK

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：

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

Node.js：OpenAI SDK

import OpenAI from "openai";

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

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"}]
  }'

Python：Anthropic SDK

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"}],
)
print(message.content[0].text)

Gemini 原生兼容接口

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

curl -sS "https://api.bestai.chat/v1beta/models" \
  -H "x-goog-api-key: $BESTAI_API_KEY"

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"}]}]}'

流式输出与图片

OpenAI 和 Anthropic SDK 都支持流式输出。只需要在客户端调用中打开对应的 stream 选项，Base URL 和认证方式不变。先用非流式短请求完成接入验证，再测试流式或长任务。

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

先用 1K、n=1 和简短提示词完成一次验证，再测试更大的尺寸或批量请求。模型、价格和分组能力以控制台当前显示为准。

接入完成标准

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

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

只有回复、没有记录，通常说明当前会话仍在使用其他 Provider 或旧配置。没有回复、但有失败记录，说明请求已经到达 BestAI，应按错误状态继续排查。

常见错误

现象	先检查什么
401 / 403	Key 是否完整、余额/额度是否可用、分组是否支持目标协议
404	Base URL 是否多填了 endpoint，或把 /v1 用在了 Anthropic SDK
模型不存在	确认模型 ID 与控制台配置提示一致，不要照抄旧示例
有回复但无使用记录	当前 Provider、Profile 或环境变量是否真的切到 BestAI
502 / 503	记录时间和模型，稍后用同一 Key 测试当前可用的另一个模型

详细处理见常见问题。