OpenAI-compatible API 接入与差异说明

CONTRACT

兼容的是接口形状，不是控制面的复制

JBB 接受一组 OpenAI 风格的 URL、认证头和 JSON 字段，使现有 SDK 更容易迁移；模型来源、路由、额度、价格和具体功能仍由 JBB 当前配置决定。

01熟悉的调用方式

替换 base_url / baseURL 和 API Key，保留已验证端点的主要请求结构。

02不同的运行时事实

可用模型、分组、倍率、限额、路由和错误正文以 JBB 当前返回结果为准。

03不承诺全量等价

端点存在不等于每个模型都支持；参数、流式、工具和多模态能力必须逐模型测试。

品牌边界

OpenAI-compatible 是协议兼容描述，不代表 JBB 与 OpenAI 存在官方合作、授权、背书或完整功能等价关系。

ENDPOINT EVIDENCE

先区分“已验证”与“路由存在”

2026-07-14 的一次性 Key 验证确认 Models 与 Chat Completions 返回 HTTP 200；2026-07-15 的生产边界探测与源代码扫描确认更多认证路由，但这些路由仍受模型和渠道能力约束。

端点	证据级别	使用边界
`GET /v1/models`	已验证	返回当前 Key 可见的模型 ID；生产请求应从这里选择模型。
`POST /v1/chat/completions`	已验证	最小非流式请求返回 HTTP 200 与 `choices`；高级字段仍需逐模型验证。
`POST /v1/responses`	条件支持	认证边界和服务端路由存在；可能直连或转换，取决于模型与渠道配置。
`POST /v1/embeddings`	条件支持	仅适用于具备 Embeddings 能力并正确配置的模型/渠道。
`POST /v1/images/generations`	条件支持	图像参数、结果格式、失败计费与模型能力不应从 Chat 端点类推。
`POST /v1/audio/speech`	条件支持	观察到认证边界；端到端能力必须使用目标音频模型单独测试。

证据口径：401 仅证明请求到达认证边界，不证明业务调用成功。实时模型与计费请以模型总览、价格页和带 Key 的 /v1/models 为准。

SDK MIGRATION

迁移只改三项：Key、Base URL、模型 ID

先把敏感值放入服务端环境变量，再从 /v1/models 选择当前可用模型。SDK Base URL 已包含 /v1，不要重复追加。

shell · 环境变量

export JBB_API_KEY="<YOUR_API_KEY>"
export JBB_BASE_URL="https://downstream.jbbtoken.cn/v1"
export JBB_MODEL="<MODEL_ID_FROM_/v1/models>"

先读取模型，再发送最小请求

cURL

curl "$JBB_BASE_URL/models"   -H "Authorization: Bearer $JBB_API_KEY"

curl "$JBB_BASE_URL/chat/completions"   -H "Authorization: Bearer $JBB_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "'"$JBB_MODEL"'",
    "messages": [{"role": "user", "content": "Reply with OK"}]
  }'

Python · openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["JBB_API_KEY"],
    base_url=os.getenv(
        "JBB_BASE_URL",
        "https://downstream.jbbtoken.cn/v1",
    ),
)

response = client.chat.completions.create(
    model=os.environ["JBB_MODEL"],
    messages=[{"role": "user", "content": "Reply with OK"}],
)
print(response.choices[0].message.content)

JavaScript · openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.JBB_API_KEY,
  baseURL: process.env.JBB_BASE_URL ??
    "https://downstream.jbbtoken.cn/v1",
});

const response = await client.chat.completions.create({
  model: process.env.JBB_MODEL,
  messages: [{ role: "user", content: "Reply with OK" }],
});
console.log(response.choices[0].message.content);

DIFFERENCES

请求看起来相似，运行时并不相同

凭证
使用 JBB 生成的 API Key；OpenAI 官方 Key、余额或组织设置不会自动带入。
模型 ID
只能使用当前 Key 在 /v1/models 中可见的 ID。显示名称、历史示例或官方模型名不能替代实时列表。
计费与限额
价格、倍率、缓存规则、额度、分组和限速由 JBB 当前配置决定，应在实时价格与控制台核对。
参数支持
stream、tools、response_format、多模态输入等可能由上游直接支持、转换、忽略或拒绝。
错误与元数据
HTTP 状态语义通常相近，但错误正文、请求 ID、usage 字段和供应商元数据可能不同。
SDK 版本
示例针对当前 OpenAI SDK 调用形状；升级 SDK 后若默认端点或字段变化，需要重新做最小回归。

FEATURE CHECK

这些能力必须按“端点 × 模型”验证

不要因为基础 Chat 请求成功，就默认高级能力也可用。为目标模型建立一张最小测试表，并保存实际响应。

stream: true检查 SSE 事件、结束标记与断线处理。
tools / tool_choice检查工具参数与返回结构。
response_format检查 JSON/Schema 约束是否被目标模型执行。
multimodal input检查图片 URL、大小限制与模型能力。
/v1/responses检查 input/output 结构和流式事件是否需要转换。
embeddings / image / audio分别使用对应模型与端点验证，不与 Chat 混测。

最小通过线

记录请求端点、模型 ID、关键参数、HTTP 状态、返回字段与计费结果。任一项变化后重新跑同一组测试。

ERRORS & RETRIES

先修配置，再考虑重试

401
认证失败
检查是否使用 JBB Key、Bearer 前缀、Key 状态和额度。
404
路径或模型不存在
确认 Base URL 只有一个 /v1，并从实时模型列表复制 ID。
405
HTTP 方法错误
Chat Completions 使用 POST；浏览器直接打开该地址会触发 GET，不等于服务不可用。
429
额度或频率受限
检查余额、Key 限额和分组；只对可重试请求采用有上限的指数退避与 jitter。
5xx
运行时或上游失败
保存请求 ID 与错误正文；设置超时和有限重试，禁止无限轮询模型或账号。

PRODUCTION GATE

上线前完成六项检查

Key 只在服务端环境变量或 Secret Manager 中保存。
Base URL 固定为 https://downstream.jbbtoken.cn/v1，不重复追加路径。
模型 ID 来自当前 Key 的 /v1/models。
目标端点、参数与模型组合已用小额度 Key 做端到端验证。
429、5xx 与网络超时使用有限重试、指数退避和 jitter。
价格、倍率、usage 与失败场景计费已在正式流量前核对。

从 Quick Start 开始选择模型核对价格进入控制台

用 OpenAI SDK 接入 JBB：兼容范围与差异

兼容的是接口形状，不是控制面的复制

先区分“已验证”与“路由存在”

迁移只改三项：Key、Base URL、模型 ID

先读取模型，再发送最小请求

请求看起来相似，运行时并不相同

这些能力必须按“端点 × 模型”验证

先修配置，再考虑重试

上线前完成六项检查