OpenAI SDK

既存の OpenAI SDK アプリケーションは、Base URL、プランキー、モデル ID を変更するだけで利用できます。アプリケーションの現在のフレームワークやエラーハンドリングはそのまま使用できます。

項目	値
Base URL	`https://api.hop-base.com/v1`
キーの環境変数	`HOPBASE_OPENAI_API_KEY`
対応モデル	GPT、Gemini、GLM チャット、その他 OpenAI 互換モデル
モデル ID	使用するキーで `GET /v1/models` を呼んだ際に返される ID を使用

インストールして最小構成のリクエストを送る

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": "Hello"}],
)
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を参照してください。
1 つのアプリケーションで両方を使う場合は、両方のグループを 1 つのキーに追加するか、上の例のようにキーを 2 つ用意して別々の環境変数(例:HOPBASE_IMAGE_API_KEY を追加)に入れてください。

実際のキーをソースコードに含めないでください。HOPBASE_OPENAI_API_KEY はデプロイ先のプラットフォーム、ローカルの .env ファイル、またはシステムの環境変数経由で注入し、.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`
`messages`	Chat Completions では必須	array、1 件以上	—	ないと 400 `missing messages field`、空配列は 400 `messages must not be an empty array`
`input`	Responses では必須	string または array	—	文字列は 1 件のユーザーメッセージに自動で包まれます
`max_tokens` / `max_completion_tokens` / `max_output_tokens`	任意	integer。ゲートウェイは切り詰めも書き換えもしない	モデルのデフォルト	上限はモデルの公式仕様に従い、超えるとモデルがエラーを返します
`stream`	任意	boolean	`false`	`true` で SSE を返します
`stream_options.include_usage`	任意	boolean	`false`	ストリーミング時に `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 フィールドにそのリクエストのトークン使用量が入ります。

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Describe yourself in three sentences"}],
    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:  # Last event: choices is empty, only usage is set
        print()
        print(chunk.usage)

今回の課金額を読む

課金されたストリーミングでないリクエストは、残高から実際に差し引かれた米ドル額をレスポンスヘッダー X-HopBase-Cost-USD で、同じ課金額の人民元額を X-HopBase-Cost で、X-HopBase-Cost の通貨(常に CNY)を X-HopBase-Currency で返します。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": "Look up the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]
messages = [{"role": "user", "content": "What's the weather like in Shanghai today?"}]

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)
    # Run the tool, then feed the result back; tool_call_id must match the previous call.id
    messages += [msg, {"role": "tool", "tool_call_id": call.id, "content": "Sunny, 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,    # seconds; prefer streaming for long outputs
    max_retries=2,  # automatic retries for connection errors, 429, and 5xx
)

次のステップ

画像生成は画像生成 API、Gemini のチャットは Gemini チャットを参照してください
Claude モデルには Anthropic SDK を使います
エラーが出たときはエラー早見表を参照してください