5 分钟完成第一次 API 调用

STEP 01

创建一枚独立的 API Key

登录控制台后进入“API 密钥”，按项目或环境分别创建 Key。不要把 Key 放进前端代码、截图、Git 仓库或公开日志。

STEP 02

设置 Base URL 与环境变量

JBB 的 SDK Base URL 已包含 /v1。配置 SDK 时不要再次追加 /v1。

• SDK Base URLhttps://jbbt.pages.dev/v1
• Chat Endpointhttps://jbbt.pages.dev/v1/chat/completions
• AuthorizationBearer $JBB_API_KEY

macOS / Linux

export JBB_API_KEY="<YOUR_API_KEY>"
export JBB_BASE_URL="https://jbbt.pages.dev/v1"

Windows PowerShell

$env:JBB_API_KEY = "<YOUR_API_KEY>"
$env:JBB_BASE_URL = "https://jbbt.pages.dev/v1"

STEP 03

用 cURL 发出第一条请求

下面使用已完成连通验证的 agnes-1.5-flash。模型 ID 会随站点配置变化，正式接入前请在模型总览确认当前可用模型。

curl "$JBB_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $JBB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-1.5-flash",
    "messages": [
      {"role": "user", "content": "Reply with OK"}
    ],
    "max_tokens": 16,
    "stream": false
  }'

成功标志：HTTP 200，响应 JSON 中包含 choices。

先检查 Key 能看到哪些模型

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

SDK

复用 OpenAI SDK

只需替换 base_url / baseURL，其余调用方式保持 OpenAI-compatible。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["JBB_API_KEY"],
    base_url="https://jbbt.pages.dev/v1",
)

response = client.chat.completions.create(
    model="agnes-1.5-flash",
    messages=[
        {"role": "user", "content": "Reply with OK"}
    ],
    max_tokens=16,
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.JBB_API_KEY,
  baseURL: "https://jbbt.pages.dev/v1",
});

const response = await client.chat.completions.create({
  model: "agnes-1.5-flash",
  messages: [
    { role: "user", content: "Reply with OK" },
  ],
  max_tokens: 16,
});

console.log(response.choices[0].message.content);

TROUBLESHOOTING

先看状态码，再查配置

不要对所有错误无限重试。先确认状态码和错误消息，再决定是否更换 Key、模型或降低请求频率。

• 401
  认证失败

  检查 Authorization: Bearer ...、Key 是否启用或过期，以及环境变量是否在当前进程中生效。

• 404
  路径或模型不存在

  确认 Base URL 只包含一次 /v1，并从模型总览复制当前模型 ID。

• 429
  额度或频率受限

  检查 Key 额度、账户余额与当前分组限制；采用指数退避，不要无间隔重复请求。

DONE

上线前再检查四件事

• API Key 只保存在服务端环境变量或 Secret Manager。
• 模型 ID 来自当前模型列表，而不是历史示例或显示名称。
• 为 429、5xx 和网络超时设置有限次数的退避重试。
• 在正式流量前，用小额度 Key 完成一次端到端测试。