OpenAI SDK HTTPX2 移行ガイド

OpenAI Python SDK は今後は、HTTP クライアントに HTTPX2 を採用します。インストール時には自動的に追加され、旧パッケージの

httpx

1. デフォルト設定の変更

SDK の既定値を使用する場合、以下の機能はそのまま動作します：

• API コール、レスポンスモデルのパース、ストリーミング、認証、リトライ、数値型タイムアウト

注意: インストール時に

httpx

• 明示的に依存関係として追加するか、
• 既存の

  httpx

  使用箇所を

  HTTPX2

  に移行してください。

from openai import OpenAI

client = OpenAI(timeout=30.0)
response = client.responses.create(model="gpt-5.5", input="Hello")

2. TLS 証明書と信頼ストアの変更

デフォルトの TLS 信頼ストアが変更されました：

• 以前:

  certifi

  パッケージによる CA バンドル検証
• 現在: オペレーティングシステムの信頼ストアを使用（

  certifi

  は不要）

影響を受ける環境

• システム CA 証明書がない最小限のコンテナイメージ
• 企業用 TLS 検査プロキシを使用する環境
• カスタム

  certifi

  バンドルに依存していたデプロイメント

対処法

1. オペレーティングシステムの証明書をインストールする（推奨）
2. 明示的な証明書バンドルを設定する：

export SSL_CERT_FILE=/path/to/ca-bundle.pem

あるいは、CA 証明書ディレクトリを構成：

export SSL_CERT_DIR=/path/to/ca-directory

上記の環境変数は

trust_env=True

import ssl
from openai import OpenAI, DefaultHttpx2Client

ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))

非同期設定の場合は

DefaultAsyncHttpx2Client

3. カスタム HTTP クライアントの提供

HTTPX2

import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

# プロキシ設定
proxy_client = OpenAI(http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080"))

# 交通とタイムアウトの設定
transport_client = OpenAI(
    http_client=DefaultHttpx2Client(
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
        timeout=httpx2.Timeout(30.0, connect=5.0),
    )
)

# 非同期クライアント
async_client = AsyncOpenAI(http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0)))

重要な注意点

• 直接構築した

  httpx2.Client

  や

  httpx2.AsyncClient

  もサポートされていますが、HTTPX2 の固有のデフォルト値が適用されることを理解してください。

• DefaultHttpxClient

  /

  DefaultAsyncHttpxClient

  という名前のクラスも機能しますが、明示的に HTTPX2 クライアントを構築する

  DefaultHttpx2Client

  /

  DefaultAsyncHttpx2Client

  の使用を推奨します。

モジュールレベルの設定例：

import openai
openai.http_client = openai.DefaultHttpx2Client()

4. オブジェクト名の置き換え

HTTPX 固有のオブジェクトは、以下の対応する HTTPX2 オブジェクトに置き換えてください：

httpx.Client

httpx2.Client

httpx.AsyncClient

httpx2.AsyncClient

httpx.Timeout

httpx2.Timeout

httpx.URL

httpx2.URL

httpx.Limits

httpx2.Limits

httpx.HTTPTransport

httpx2.HTTPTransport

httpx.AsyncHTTPTransport

httpx2.AsyncHTTPTransport

httpx.MockTransport

httpx2.MockTransport

細粒度なタイムアウト設定例

import httpx2
from openai import OpenAI

client = OpenAI(timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0))

※数値型タイムアウト値や文字列 URL 形式は変更ありません。

5. 認証とイベントフック

認証ハンドラーとフックは、HTTPX2 の

Request

Response

import httpx2
from openai import OpenAI, DefaultHttpx2Client


def log_request(request: httpx2.Request) -> None:
    print(request.method, request.url)


client = OpenAI(http_client=DefaultHttpx2Client(event_hooks={"request": [log_request]}))

• カスタム認証クラスや注釈も

  httpx2

  に対応したインターフェースを使用してください。
• サードパーティ製ツール（計測、トレーシング、認証統合）は明示的に HTTPX2 をサポートしている必要があります。

6. 生レスポンス、ストリーミング、例外処理

• パースされた SDK レスポンスモデルには変更はありません。
• ネイティブ

  HTTPX2

  クライアントを使用する場合、

  http_response

  および

  http_request

  は

  httpx2

  の型になります：

import httpx2
from openai import OpenAI

client = OpenAI()
response = client.models.with_raw_response.list()

assert isinstance(response.http_response, httpx2.Response)
assert isinstance(response.http_request, httpx2.Request)

• 未パースの HTTP レスポンスを要求する場合は

  cast_to=httpx2.Response

  を指定してください。
• ストリーミングレスポンスラッパーも

  httpx2.Response

  オブジェクトを公開します。
• アプリケーションコードでは、通常は

  openai.APITimeoutError

  や

  openai.APIConnectionError

  などの SDK 例外をキャッチすべきです。
• ネイティブクライアントを使用する場合、通信部分の例外は

  HTTPX2

  例外になります。

型保証の注意点 これらの保証はネイティブ

HTTPX2

httpx

cast_to=httpx2.Response

httpx

7. aiohttp サポートの変更

サポートされている

aiohttp

pip install 'openai[aiohttp]'

from openai import AsyncOpenAI, DefaultAioHttpClient

client = AsyncOpenAI(http_client=DefaultAioHttpClient())

• DefaultAioHttpClient()

  は内部で

  httpx2.AsyncClient

  を使用します。
• 通信部分を直接構築したりインポートする必要はありません。

8. モックとテスト

モックは必ず HTTPX2 リクエストをインターセプトし、HTTPX2 レスポンスを返す必要があります：

import httpx2
from openai import OpenAI


def handler(request: httpx2.Request) -> httpx2.Response:
    return httpx2.Response(
        200,
        request=request,
        json={"object": "list", "data": []},
    )


client = OpenAI(http_client=httpx2.Client(transport=httpx2.MockTransport(handler)))

assert client.models.list().data == []

RESPX のバージョン更新 テストスイートが

RESPX

httpx

9. 一時的なエスケープハッチ：従来の HTTPX クライアント

移行期間中のみ、従来の

httpx

クライアントの指定

from typing import Any, cast

import httpx
from openai import OpenAI

client = OpenAI(http_client=cast(Any, httpx.Client()))

同様に非同期クライアントも：

from typing import Any, cast

import httpx
from openai import AsyncOpenAI

client = AsyncOpenAI(http_client=cast(Any, httpx.AsyncClient()))

生レスポンスの扱い

従来のクライアントを使用する場合、

httpx.Response

httpx

from typing import Any, cast

import httpx
from openai import OpenAI

client = OpenAI(http_client=cast(Any, httpx.Client()))
response = client.get("/models", cast_to=cast(Any, httpx.Response))

assert isinstance(response, httpx.Response)

※

cast_to=httpx2.Response

10. 既存の aiohttp アダプターの維持

既存の

httpx-aiohttp

pip install openai httpx-aiohttp

from typing import Any, cast

from httpx_aiohttp import HttpxAiohttpClient
from openai import AsyncOpenAI

client = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient()))

• この方法は専用互換性テストでカバーされていますが、一時的なエスケープハッチです。
• 新規コードでは

  openai[aiohttp]

  と

  DefaultAioHttpClient()

  の使用を強く推奨します。