跳到正文
HopBase 文档
登录控制台

OpenAI SDK

使用 OpenAI Python 或 Node.js SDK 调用 HopBase。

现有 OpenAI SDK 项目只需切换 Base URL、分组密钥和模型 ID；请保留当前的框架与错误处理。

项目填写值
Base URLhttps://api.hop-base.com/v1
密钥环境变量HOPBASE_OPENAI_API_KEY
适用模型GPT、Gemini、GLM 对话模型，以及 OpenAI 兼容模型
模型 ID以当前密钥调用 GET /v1/models 的返回值为准

安装并发送最小请求

安装 SDK：

python -m pip install openai

发送请求：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key=os.environ["HOPBASE_OPENAI_API_KEY"],
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

先将提示词设为「只回复 ok」完成最小验证；只有项目实际使用流式时，再加入 stream: true 并确认 SSE 事件可以逐段到达。

对话和生图在不同分组：
  • GPT 对话与 Responses：「Codex Plus」「Codex Pro」或「GPT 官方直连(Azure)」分组。Gemini、GLM 等其他对话模型在各自的分组。
  • 生图（gpt-image-*）：「GPT Image 全系」分组含全系列；「GPT 官方直连(Azure)」分组也有 gpt-image-2.5-flare 与 gpt-image-2.5-sunburst。密钥里没有含该型号的分组时返回 404。用法见图片生成 API。
  • 同一个项目两者都用时，把两个分组加进同一把密钥；或像上面的示例那样用两把密钥，分别放进不同的环境变量（例如另设 HOPBASE_IMAGE_API_KEY）。

不要把真实密钥写进源码。请通过部署平台、.env 或系统环境变量注入 HOPBASE_OPENAI_API_KEY，并确保 .env 不会提交到 Git。

支持的请求参数

下表只列网关会检查、改写或拒绝的字段（POST /v1/chat/completions 与 POST /v1/responses）；未列出的 OpenAI 字段原样转发，取值范围按模型官方规格。各模型的上下文与输出上限见模型列表；Gemini 的分组差异见 Gemini 对话。

参数必填类型与限制默认说明
model必填string，当前密钥分组内的模型 ID—分组不包含该模型时返回 404 model_not_found；gpt-image-* 等图片模型调对话端点返回 400 image models do not support Chat Completions, please use the Images API
messagesChat Completions 必填array，至少 1 条—缺失返回 400 missing messages field，空数组返回 400 messages must not be an empty array
inputResponses 必填string 或 array—字串会自动包成单条用户消息
max_tokens / max_completion_tokens / max_output_tokens可选integer；网关不截断、不改写模型默认上限按模型官方规格；超出由模型返回错误
stream可选booleanfalsetrue 返回 SSE
stream_options.include_usage可选booleanfalse流式时传 true 才会收到最后一个只带 usage 的事件；不传则不下发（计费不受影响）
tools / tool_choice可选OpenAI function tools 格式—原样转发
service_tier可选只保留 priority / flex；fast 视为 priority—其他取值会被移除后再转发，不报错。Fast（priority）仅在所用分组支持时生效并按 Fast 价计费，不支持时按标准档处理、按标准价计费
previous_response_id—不支持（Responses）—网关会移除此字段，不会接续上一轮；多轮对话请在 input 里带上完整历史
store—固定为 false（Responses）false服务端不保存响应，不能事后按 ID 取回

整个请求体上限 60 MB，超过返回 413。

GPT 官方直连(Azure)分组的差异：
  • 型号名与 OpenAI 官方一致。对话：gpt-6-sol、gpt-6-luna、gpt-6-astra、gpt-6.1-sol、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4；生图：gpt-image-2.5-flare、gpt-image-2.5-sunburst（/v1/images/generations 与 /v1/images/edits，同步返回 Base64）。不含 codex-* 与 gpt-image-2。
  • 不支持 service_tier: "priority"（含 fast）：按标准档处理、按标准价计费。
  • 响应里的 model 可能是带日期的快照名（例如 gpt-5.5-2026-04-24），与 OpenAI 官方 API 行为一致；计费按请求的模型 ID，控制台「使用记录」也可能显示快照名。不要用 response.model == request.model 做断言。

流式输出并取得用量

传 stream_options.include_usage 后，最后一个事件的 choices 为空，usage 是本次 token 用量。

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "用三句话介绍你自己"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:  # 最后一个事件：choices 为空，只带用量
        print()
        print(chunk.usage)

读取本次扣费

计费的非流式请求会在响应头 X-HopBase-Cost-USD 里返回本次实际从余额扣除的美元金额，X-HopBase-Cost 是同一笔扣费的人民币金额，X-HopBase-Currency 是 X-HopBase-Cost 的币种（恒为 CNY）；JSON 响应的 usage 里也有同样的 cost、cost_usd 与 currency，SDK 会把它们当作额外字段保留。流式响应都不带，扣费请到控制台「使用记录」查看。完整口径见扣费说明。

raw = client.chat.completions.with_raw_response.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "只回复 ok"}],
)
print(raw.headers.get("x-hopbase-cost"), raw.headers.get("x-hopbase-cost-usd"), raw.headers.get("x-hopbase-currency"))
resp = raw.parse()  # 与不带 with_raw_response 时的返回值相同
print(resp.usage.cost, resp.usage.cost_usd, resp.usage.currency)  # 额外字段，与响应头同值

工具调用

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]
messages = [{"role": "user", "content": "上海今天天气怎样？"}]

resp = client.chat.completions.create(model="gpt-5.6-sol", messages=messages, tools=tools)
msg = resp.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    print(call.function.name, call.function.arguments)
    # 执行工具后把结果带回去，tool_call_id 必须与上一轮的 call.id 一致
    messages += [msg, {"role": "tool", "tool_call_id": call.id, "content": "晴，26°C"}]
    resp = client.chat.completions.create(model="gpt-5.6-sol", messages=messages, tools=tools)
print(resp.choices[0].message.content)

超时与重试

openai-python 与 openai-node 默认读超时 600 秒、自动重试 2 次。长输出建议用流式；并发上限与超时见并发、超时与计费。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key=os.environ["HOPBASE_OPENAI_API_KEY"],
    timeout=600,    # 秒；长输出建议改用流式
    max_retries=2,  # 连接错误、429 与 5xx 的自动重试次数
)

下一步

本页目录

安装并发送最小请求支持的请求参数流式输出并取得用量读取本次扣费工具调用超时与重试下一步