跳到正文
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 的自動重試次數
)

下一步

本頁目錄

安裝並發送最小請求支援的請求參數串流輸出並取得用量讀取本次扣費工具調用超時與重試下一步