Python SDK の概要

公開済みの ~~phaseo~~ パッケージを PyPI からインストールします。 Phaseo Python SDKは同期クライアントPhaseoとネイティブ非同期クライアントAsyncPhaseoを提供します。

ネイティブ非同期リクエスト

import asyncio
from phaseo import AsyncPhaseo

async def main():
    async with AsyncPhaseo() as client:
        response = await client.responses.create({"model": "openai/gpt-5-nano", "input": "Hello"})
        print(response.output_text, response.request_id, response.trace_url)

asyncio.run(main())

解析済みテキストイベントにはasync for event in client.responses.stream(request)を使います。 asyncioのネイティブキャンセルでHTTPとポーリングが停止します。リソースはテキスト、画像、音声、音楽、動画、バッチ、ファイル、モデル、埋め込み、OCR、再ランキング、解析、モデレーション、判断をカバーします。その他のHTTP操作はawait client.request(...)を使います。注入したHTTPXクライアントは呼び出し元が管理します。両クライアントは元のクライアントを変更せずにwith_options(timeout=30, max_retries=2)をサポートします。HTTPXのタイムアウトはネットワークの無通信時間を秒で制限します。再試行は既定で0回で、応答を読む前のGET/HEADにのみ適用され、送信には適用されません。 PhaseoHTTPErrorは本文、コード、リクエストID、トレースURL、再試行遅延を公開します。更新時は同期JSONリクエストでのurllib.error.HTTPErrorの捕捉を PhaseoHTTPError（またはhttpx.HTTPStatusError）に変更し、接続エラーの捕捉を httpx.TransportErrorに変更します。error.statusはHTTPステータスで、error.codeは APIエラーコードです。

追加の便利な機能

ジョブリソースはresult、events、to_dictを持つstartとresumeのハンドルを提供します。非同期メソッドを待機し、async forで非同期イベントを反復します。リモートキャンセルは動画とバッチのみ対応します。メディアは videos.stream_content(id)、バッチはbatches.results(id)でストリーミングします。同期の download_to(chunks, binary_file)はファイル全体をバッファリングせず書き込みます。アップロードはバイト列、Pathオブジェクト、ファイルオブジェクト、HTTPXファイルタプルを受け付けます。 responses.parse(request, PydanticModel)は完了したJSON出力を検証します。サーバーの応答形式を明示してください。collect_streamと collect_async_streamは解析済みテキストイベントと使用量を集めます。 check_model_capabilities(id, input_types=..., output_types=..., endpoints=..., parameters=..., parameter_values=...)は1つの利用可能なプロバイダー提供に対する公開機能とスカラー制約をまとめて確認します。不明な情報があると事前確認は失敗します。モデル選択やパラメーター編集には、現在のエンドポイントメタデータを使います。

support = client.models.check_parameters(
    "openai/gpt-5",
    {"temperature": 0.7, "top_p": 0.9},
    endpoint="responses",
)

各パラメーターはsupported、partial、unsupported、unknownと示され、対応するプロバイダールートと表示に使える制約の問題が含まれます。 client.models.capabilities(model_id)はエンドポイントの機能応答全体を返します。AsyncPhaseoは同じメソッドをawait可能な形で提供します。ローカルテストにはhttpx.Clientまたはhttpx.AsyncClientで phaseo.testing.MockTransportを注入します。想定外のリクエストはローカルで失敗し、assert_done()で全テストデータの使用を確認できます。実際のプロバイダー動作を検証するものではありません。 Phaseoルームはコードを取得で送信したリクエストの実行可能コードをエクスポートします。

主な機能

OpenAPI 仕様から生成された型付きリクエストモデル。
チャット、Responses、Messages、画像、音声、埋め込み、モデレーション、ファイル、バッチ、生成、非同期動画ジョブ用の組み込みヘルパー。
テキスト、Responses、Messages 用のストリーミングヘルパー（stream_* イテレーター）。
制御プレーン用のヘルパーとして、モデル、エンドポイント、組織、料金の確認と計算、APIキーとワークスペースのライフサイクル管理、現在のキーの確認、ヘルス状態、プロバイダー、クレジット、アクティビティ、分析を利用できます。

簡単な例

from phaseo import Phaseo

client = Phaseo(api_key="your-api-key")

response = client.generate_response(
    {
        "model": "openai/gpt-5-nano",
        "input": "Reply with: python sdk works",
    }
)

print(response.get("id"))

音楽・動画・バッチの完了を待つ

import os

music = client.music.generate_and_wait(
    {"model": os.environ["PHASEO_MUSIC_MODEL"], "prompt": "Gentle instrumental piano"},
    timeout=600,
    on_poll=lambda job: print(job["id"], job["status"]),
)

動画にはvideos.generate_and_wait(request, **options)、バッチにはbatches.create_and_wait(request, **options)を使います。同期ヘルパーは1回だけ送信し、必要時のみポーリングして完了応答全体を返します。JobFailedError.responseは失敗、キャンセル、期限切れの詳細を保持します。完了したバッチにも個別の失敗が含まれる場合があります。各リソースはwait(id, **options)で既存ジョブを再開し、すべての最終応答を返せます。音楽には直接呼べるcreate(request)とretrieve(id)もあります。オプションはinterval（秒、既定5、最小0.25）、timeout（秒、既定1800）、on_poll、cancel_event（threading.Event）です。待機タイムアウトは送信から戻った後に開始します。同期クライアントはリクエストとコールバックの間にキャンセルと期限を確認しますが、これらのオプションで進行中のHTTP呼び出しは中断できません。 JobTimeoutErrorとJobCancelledErrorはjob_idとlast_responseを保持します。.wait(error.job_id)で再開してください。ローカルのタイムアウトやキャンセルはリモートジョブを停止せず、送信も自動再試行されません。ヘルパーはGatewayにバックグラウンド実行を追加しません。

“含まれるもの”

Phaseo クライアント
chat.completions.create(...) and responses.create(...) 互換ヘルパー
リソースヘルパー（例:） client.batches, client.videos, client.files, and client.async_jobs
バッチと動画のライフサイクルストリーム用非同期ジョブ WebSocket URL ヘルパー
client.batches.stream_results(batch_id) バッチJSONLのバイトチャンク用
モデルのライフサイクル用ヘルパー（例:） get_model_deprecation_info(...) and validate_model(...)
テキスト、Responses、Messages 用のストリーミングイテレーター
~~phaseo.models~~ にある生成済みリクエスト/レスポンスモデル

はじめに

現在対応している機能

SDK で近日対応予定

ネイティブ非同期リクエスト

追加の便利な機能

主な機能

簡単な例

音楽・動画・バッチの完了を待つ

“含まれるもの”

​ネイティブ非同期リクエスト

​追加の便利な機能

​主な機能

​簡単な例

​音楽・動画・バッチの完了を待つ

​“含まれるもの”

ネイティブ非同期リクエスト

追加の便利な機能

主な機能

簡単な例

音楽・動画・バッチの完了を待つ

“含まれるもの”