统一的 AI 文本接口

通过统一地址和 API 密钥调用文本与代码模型。当前开发者接口支持 Claude Messages、Chat Completions、Responses 和模型列表，右侧示例栏可以直接发请求试。

https://api.bigao.ai/v1

使用 Bearer 密钥鉴权

每次请求都需要在 Header 中携带控制台创建的完整密钥。控制台默认打码显示，登录后可按需查看和复制。

Authorization: Bearer bgai_你的密钥

不要把密钥写进前端代码或公开仓库。服务端读取环境变量，并为测试、生产环境分别创建密钥。

选择需要的接口

四个接口共用同一个地址和同一把密钥，按你现有代码用的协议挑一个即可。

CClaude Messages兼容 Anthropic Messages 协议 聊天补全兼容 OpenAI Chat Completions ResponsesCodex 等 Agent 工具走这条 M支持模型查找并复制当前公开模型 ID

Claude 消息接口

POST/v1/messages

完全兼容 Anthropic Messages 协议。已经在用 Anthropic SDK 的项目，只要把 base_url 换成比高、密钥换成 bgai_ 开头的那把，其余代码不用动。

鉴权

Authorizationstring必填: Bearer 加上控制台创建的完整密钥，例如 Bearer bgai_xxx。
anthropic-versionstring必填: 固定填 2023-06-01。Anthropic SDK 会自动带上，手写请求要自己加。

Body 参数

modelstring必填: 模型 ID，取值以控制台「支持模型」页展示的为准。
messagesobject[]必填: 对话消息，按时间顺序排列。第一条必须是 user。
max_tokensinteger必填: 本次请求允许生成的最大 token 数。超过会被截断，finish 原因为 max_tokens。
thinkingobject: 开启扩展思考。仅对支持思考的模型有效，不支持的模型会忽略该字段。
systemstring | object[]: 系统提示词。不放在 messages 里，单独传这个字段。
temperaturenumber默认 1.0: 采样温度，0 到 1。数值越低输出越稳定。
top_pnumber: 核采样。与 temperature 建议只调其中一个。
top_kinteger: 只从概率最高的 K 个候选里采样。
streamboolean默认 false: 是否以 SSE 事件流返回。流式的处理方式见下方「流式响应」。
stop_sequencesstring[]: 命中其中任意一条就停止生成，停止原因为 stop_sequence。
metadataobject: 随请求上报的元信息。
toolsobject[]: 可供模型调用的工具定义。
tool_choiceobject: 控制工具调用方式：auto 由模型决定，any 必须调用其中之一，tool 指定调用某一个。

响应字段

idstring: 本次回复的唯一 ID。
typestring: 固定为 message。
rolestring: 固定为 assistant。
contentobject[]: 内容块数组，可能同时包含多种类型。
modelstring: 实际处理请求的模型。
stop_reasonstring: end_turn 正常结束；max_tokens 达到上限；stop_sequence 命中停止词；tool_use 等待工具结果。
usageobject: 用量。计费以这里为准。

请求示例

curl https://api.bigao.ai/v1/messages \
  -H "Authorization: Bearer bgai_你的密钥" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"你的模型ID","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}'

响应示例

成功

{
  "id": "msg_01Xy...",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "你好！有什么可以帮你的？" }
  ],
  "model": "你的模型ID",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 9, "output_tokens": 12 }
}

在线调试

API 密钥请求体

密钥只用于这一次请求，不会保存在页面或我们的服务器上。调试会按实际用量计费，流式响应在这里会被强制关掉。

聊天补全接口

POST/v1/chat/completions

兼容 OpenAI Chat Completions 协议。现有 OpenAI SDK 的项目改一行 base_url 就能接过来。

鉴权

Authorizationstring必填: Bearer 加上控制台创建的完整密钥，例如 Bearer bgai_xxx。

Body 参数

modelstring必填: 模型 ID。
messagesobject[]必填: 对话消息。
max_tokensinteger: 最大输出 token 数。不传则由模型默认上限决定。
temperaturenumber默认 1.0: 采样温度。
top_pnumber默认 1.0: 核采样。
streamboolean默认 false: 是否以事件流返回。
stopstring | string[]: 停止词。
toolsobject[]: 工具定义，格式与 OpenAI 一致。
tool_choicestring | object: none / auto / required，或指定某个工具。
response_formatobject: 传 { "type": "json_object" } 要求返回合法 JSON。

响应字段

idstring: 本次补全的 ID。
objectstring: 固定为 chat.completion。
choicesobject[]: 候选回复，通常只有一条。
usageobject: prompt_tokens、completion_tokens、total_tokens。计费以此为准。

请求示例

curl https://api.bigao.ai/v1/chat/completions \
  -H "Authorization: Bearer bgai_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型ID","messages":[{"role":"user","content":"你好"}]}'

响应示例

成功

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "你的模型ID",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

在线调试

API 密钥请求体

密钥只用于这一次请求，不会保存在页面或我们的服务器上。调试会按实际用量计费，流式响应在这里会被强制关掉。

Responses 接口

POST/v1/responses

OpenAI Responses 协议。Codex 走的就是这条，需要统一输入结构的 Agent 应用也建议用它。

鉴权

Authorizationstring必填: Bearer 加上控制台创建的完整密钥，例如 Bearer bgai_xxx。

Body 参数

modelstring必填: 模型 ID。
inputstring | object[]必填: 文本，或由角色与内容块组成的结构化输入。
instructionsstring: 系统级指令，作用类似 system。
max_output_tokensinteger: 最大输出 token 数。
temperaturenumber默认 1.0: 采样温度。
top_pnumber: 核采样。
streamboolean默认 false: 是否以事件流返回。
toolsobject[]: 工具定义。
tool_choicestring | object: 工具调用策略。

响应字段

idstring: 本次响应 ID。
objectstring: 固定为 response。
statusstring: completed、incomplete 或 failed。
outputobject[]: 输出块数组，含 message、tool_call 等类型。
usageobject: input_tokens、output_tokens、total_tokens。

请求示例

curl https://api.bigao.ai/v1/responses \
  -H "Authorization: Bearer bgai_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型ID","input":"请整理今天的工作计划"}'

响应示例

成功

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "你的模型ID",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "今天的工作计划如下……" }]
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 86, "total_tokens": 98 }
}

在线调试

API 密钥请求体

密钥只用于这一次请求，不会保存在页面或我们的服务器上。调试会按实际用量计费，流式响应在这里会被强制关掉。

模型列表接口

GET/v1/models

读取这把密钥所属厂商当前可以调用的模型。请求列表外或其他厂商型号时，会回落到这把密钥的默认型号。

鉴权

Authorizationstring必填: Bearer 加上控制台创建的完整密钥，例如 Bearer bgai_xxx。

响应字段

objectstring: 固定为 list。
dataobject[]: 模型数组。

使用熟悉的 SDK

对于 Chat Completions 等已支持的文本接口，可以继续使用 OpenAI 客户端；这不代表完整覆盖 OpenAI 的所有端点。

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.bigao.ai/v1",
    api_key=os.environ["BIGAO_API_KEY"],
)

result = client.chat.completions.create(
    model="你的模型ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(result.choices[0].message.content)

流式响应

把 stream 设成 true，响应会变成 SSE 事件流：每个数据块以data: 开头，OpenAI 系协议以 data: [DONE] 收尾， Anthropic 系协议以 message_stop 事件收尾。

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.bigao.ai/v1",
    api_key=os.environ["BIGAO_API_KEY"],
)

stream = client.chat.completions.create(
    model="你的模型ID",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

流式请求的用量在整段流结束后才结算。中途断开连接，已经产生的输出仍然计费。

平台差异与对接注意

地址只换 Base URL，路径不变。原来打 /v1/chat/completions 的，现在打 https://api.bigao.ai/v1/chat/completions，路径部分照抄。

密钥绑定厂商，不绑定单个型号。同一厂商内的型号随时可切，按实际跑的那个计费。请求的型号不属于该厂商、或我们没上，会回落到该厂商的默认型号并按它计费——响应头 X-Bigao-Model-Resolution 会写明本次是 exact 还是 fallback_to_default，在意计费的话请检查这个头。

Claude Messages 要带 anthropic-version。官方 SDK 自动带，手写 HTTP 请求要自己加，缺了直接 400。

模型 ID 以实时列表为准。不要把模型 ID 硬编码进多个地方，用 /v1/models 或控制台核对。

错误处理

400请求参数错误检查 JSON、必填字段和参数格式。

401密钥无效或过期确认 Authorization Header 和密钥状态。

402余额不足在控制台补充余额后重试。

403权限或账号状态限制当前凭据没有执行该操作的权限，或账号状态限制了操作；模型回落不会返回此码。

404模型或路径不存在检查端点路径和模型 ID，并以实时模型列表为准。

429请求过快稍后重试，并在程序中使用退避策略。

5xx服务暂时异常保留 request_id，稍后重试或提交反馈。

接口 FAQ

怎么让模型稳定返回 JSON？

Chat Completions 传 response_format 为 { "type": "json_object" }，并在提示词里明确写出字段。Claude Messages 没有这个字段，用工具调用（tools）约束结构最稳，其次是在 system 里给出示例。

返回的 JSON 解析失败怎么办？

先别急着重试。多数是模型在 JSON 前后带了说明文字或 Markdown 代码围栏，取第一个 { 到最后一个 } 之间的内容再解析。反复失败时把 temperature 调低。

同样的参数在不同模型上结果不一样？

各模型支持的参数和默认值不同，不支持的字段会被忽略而不是报错。以「支持模型」页和控制台的实际选项为准。

怎么估算一次请求要花多少钱？

响应里的 usage 就是计费依据。控制台「使用记录」按调用逐条列出模型、输入输出用量和实际扣费。

调试时报 401，但密钥是刚创建的？

多半是复制少了一截，或者首尾带了空格。用右侧「在线调试」贴一次密钥打 /v1/models，能列出模型就说明密钥本身没问题。