概述

接入文档

Openbili API 完全兼容 OpenAI 接口格式，可直接使用现有 SDK。

登录后体验 API Sandbox 服务状态

Base URLHTTPS

https://api.openbili.com/v1

协议

REST / SSE

格式

JSON

兼容性

OpenAI SDK

Billing

USD

认证方式

在请求头中使用 Authorization: Bearer 进行认证。

API Key 可在登录后的控制台中创建和管理。请妥善保管您的密钥，切勿在客户端代码中暴露。

安全提示：请勿将 API Key 提交到代码仓库或在前端代码中硬编码。

接入前检查

Base URL 使用 https://api.openbili.com/v1
请求头使用 Authorization: Bearer <OPENBILI_API_KEY>
模型 ID 以控制台「模型广场」和 API Key 可用范围为准
服务端保存 API Key，前端代码不要硬编码密钥

API 入口

OpenAI Chat

/v1/chat/completions

OpenAI SDK 兼容的聊天补全入口，适合 GPT、Claude、DeepSeek 等文本/多模态模型。

OpenAI Responses

/v1/responses

Responses API 兼容入口，适合使用新式 OpenAI 客户端的应用。

Images

/v1/images/generations

图像生成入口，返回可直接渲染或下载的结果 URL。

Anthropic Messages

/v1/messages

Anthropic 原生 Messages 入口，适合 Claude SDK 和长上下文调用。

代码示例

cURL

curl https://api.openbili.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENBILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      { "role": "user", "content": "Hello from Openbili" }
    ]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENBILI_API_KEY"],
    base_url="https://api.openbili.com/v1",
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Hello from Openbili"}],
)

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

支持模型

登录后可在「模型广场」查看当前账号实际可用模型与价格。

供应商	模型名	适用场景
Claude	claude-opus-4-7, claude-sonnet-4-6	长上下文、推理、复杂 Agent
GPT	gpt-5, gpt-5.4, gpt-4.1	通用对话、工具调用、代码任务
Gemini	gemini-3-pro-image-preview, gemini-3.1-flash-image-preview	图片理解与图片生成
Image	gpt-image-2, gpt-image-1.5	高质量图片生成与编辑

常见失败与提交证据

失败响应或用量明细里的 trace_id / request_id 是定位问题的关键。重试一次仍失败时，请从用量页创建诊断工单，系统会自动带上模型、状态码、错误码和重试建议。

认证或 Key 范围错误

状态：401 / 403 / invalid_api_key

处理建议

通常是 API Key 不完整、已停用、环境变量读错，或该 Key 没有请求模型的权限。

下一步：先用 /v1/models 验证 Key 和模型范围；若 Key 暴露过，立即在控制台轮换。

提交证据：提交 request_id、trace_id、模型名和 Key 前缀，绝不要提交完整 API Key。

可复制示例

curl https://api.openbili.com/v1/models \
  -H "Authorization: Bearer $OPENBILI_API_KEY"

# 401 / 403:
# 1. Confirm the key is active and complete.
# 2. Confirm this key allows the requested model.
# 3. Rotate the key if it was copied into an unsafe environment.

额度、限速与 retry-after

状态：402 / 429 / rate_limit_exceeded

处理建议

402 通常与余额或额度有关；429 说明 RPM/TPM 或上游限流触发。响应头里的 Retry-After 是最小等待时间。

下一步：按 Retry-After 等待后只重试一次；重复出现时从 Usage 创建诊断工单。

提交证据：提交 status、error_code、retry-after、request_id、trace_id 和发生时间。

可复制示例

curl -i https://api.openbili.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENBILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"ping"}]}'

# 429:
# Read Retry-After: <seconds>, wait at least that long,
# then retry once. If it repeats, create a Usage diagnostic ticket.

模型未就绪或不可见

状态：404 / model_not_ready / model_not_allowed

处理建议

客户可见模型必须同时满足 route、pricing、probe OK；如果模型没有出现在 /v1/models，就不应在生产调用中使用。

下一步：在模型广场或 /v1/models 选择当前 Key 返回的模型；如业务需要缺失模型，请创建工单。

提交证据：提交模型名、Key 前缀、request_id、trace_id 和 /v1/models 是否返回该模型。

可复制示例

curl https://api.openbili.com/v1/models \
  -H "Authorization: Bearer $OPENBILI_API_KEY" | jq '.data[].id'

# Use only models returned by /v1/models for this key.
# Customer-visible models require route + pricing + probe OK.

上游超时或平台 5xx

状态：5xx / timeout / upstream_or_platform_error

处理建议

短暂上游波动可能会恢复；重复失败时 trace_id/request_id 能让运维定位具体上游、路由和重试链路。

下一步：短暂等待后重试一次；如果同一模型持续失败，从 Usage 创建诊断工单。

提交证据：提交 no-secret 诊断包即可，包含 source、request_id、trace_id、model、status、error_class 和 error_code。

可复制示例

{
  "source": "usage",
  "request_id": "req_xxx",
  "trace_id": "trace_xxx",
  "model": "claude-sonnet-4-6",
  "status": 504,
  "error_class": "upstream_or_platform_error",
  "error_code": "upstream_timeout"
}

价格快照与可计费失败

计费：pricing / billing_result / failed_but_billable

处理建议

Openbili 使用 USD 计费，并在请求开始时冻结价格快照。某些上游已消耗 token 的失败请求仍可能显示为可计费失败。

下一步：在 Usage 或导出账单里查看 cost_usd、billing_result 和 price_snapshot；对金额有疑问时提交工单。

提交证据：提交 request_id、model、cost_usd、billing_result、price_snapshot 和发生时间，不需要提交 prompt 内容。

可复制示例

{
  "request_id": "req_xxx",
  "model": "gpt-5",
  "billing_result": "failed_but_billable",
  "cost_usd": "shown in Usage",
  "price_snapshot": "shown in Usage export"
}

流式响应中断

流式：stream=true / SSE / partial_output

处理建议

流式请求开始返回字节后，客户端断连或上游中断可能已经产生部分输出和用量。

下一步：已收到部分输出时不要盲目重放非幂等任务；保存 trace_id/request_id 后创建诊断工单。

提交证据：提交 request_id、trace_id、模型、是否已收到 token、客户端断开时间和错误消息。

可复制示例

curl -N https://api.openbili.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENBILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","stream":true,"messages":[{"role":"user","content":"stream one sentence"}]}'

# If bytes already streamed before a disconnect, do not blindly replay
# non-idempotent work. Save trace_id/request_id and open a diagnostic ticket.

max_tokens 自动限制

网关会自动把 max_tokens clamp 到每个模型的输出上限。客户端无需特殊处理，超限请求会按模型上限截断而非报错。

进入驾驶舱