メインコンテンツへスキップ
使う言語の Phaseo パッケージをインストールし、API キーでクライアントを作成すれば、Gateway のエンドポイントごとに 1 つのメソッドを呼び出せます。キーを渡さない場合、どの SDK も PHASEO_API_KEY を読み込みます。 各言語のインストールコマンドと要件はインストールにあります。C++ SDK はまだリリースされていません。

送るものと返ってくるもの

どの SDK でも、リクエスト本文には API の JSON フィールド名を使います。エンドポイントごとの例は使い方にあります。 キーがない場合は、クライアントの作成時に失敗します。Python は ValueError を送出し、Go の NewFromEnv() はエラーを返し、C# と PHP は Missing API key. Pass apiKey or set PHASEO_API_KEY. をスローし、Ruby は ArgumentError: Missing API key. Pass api_key or set PHASEO_API_KEY. を送出し、Rust の Phaseo::from_env() は PhaseoError を返します。

各エンドポイントのメソッドを見つける

ダッシュは、その SDK にその操作のラッパーがないことを示します。最後の行のメソッドを使うか、HTTP API を直接呼び出してください。「JSON のみ」は、そのメソッドがマルチパートのファイルアップロードを送れないことを意味します。代わりに URL か base64 のデータ URL を渡すか、エンドポイントのページにあるとおり、使う言語の HTTP クライアントでアップロードを送ってください。ほとんどの SDK には、各 generate… メソッドに対応する create… の別名もあります(たとえば Go と C# の CreateChatCompletion、Ruby の create_response)。 C#、PHP、Ruby、Java にはアップロード用のメソッドがありますが、JSON を送るためファイルはアップロードできません。各言語のマルチパートリクエストはファイルと STT にあります。キーとワークスペースには、Rust を除くすべての SDK で get、update、delete のメソッドと現在のキーの照会(getCurrentApiKey、get_current_api_key、GetCurrentApiKey)もあります。TypeScript と Python は、音楽、OCR、解析、判断、抽出にも対応しています。

各パッケージに含まれるものを確認する

公開済みのパッケージは、SDK のソースにある一部の機能より前のものです。

クライアントを設定する

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

待機用のヘルパーは TypeScript と Python にあります。その他の SDK は作成の呼び出しでジョブを返すので、取得メソッドでポーリングするか、そのジョブの WebSocket URL を開いてください。
動画には videos.generateAndWait / videos.generate_and_wait を、バッチには batches.createAndWait / batches.create_and_wait を使います。各ヘルパーは 1 回だけ送信します。最初のレスポンスがすでに完了していればポーリングせずにそれを返し、そうでなければ同じジョブを完了までポーリングして完全なレスポンスを返します。失敗、キャンセル、期限切れになったジョブは JobFailedError を送出し、その response に詳細が含まれます。完了したバッチにも、個々のリクエストの失敗が含まれている場合があります。 各リソースの wait(id, options) は既存のジョブを再開し、失敗を含む終了時のレスポンスを返します。Python では、音楽に create(request) と retrieve(id) もあります。 JobTimeoutError と JobCancelledError はジョブ ID と最後のレスポンス(TypeScript では jobId/lastResponse、Python では job_id/last_response)を保持するため、.wait(error.jobId) または .wait(error.job_id) で再開できます。待機を停止しても、リモートのジョブはキャンセルされません。TypeScript では実行中のポーリングがキャンセルされます。同期の Python クライアントはリクエストとコールバックの間でキャンセルと期限を確認するため、すでに進行中の HTTP 呼び出しは中断できません。HTTP の失敗はそのまま送出され、送信は再試行されません。これらのヘルパーはあなたのプロセスからポーリングするもので、Gateway にバックグラウンド実行を追加するものではありません。

プロセスをまたいでハンドルを保持する

music.start、videos.start、batches.start は、result()、events()、cancel()、さらに toJSON()(TypeScript)または to_dict()(Python)を持つハンドルを返します。返される種類と ID を保存しておき、後で resume(id) でハンドルを再構築します。result() は終了時の失敗で例外を送出します。cancel() に対応しているのは動画とバッチのジョブだけです。AsyncPhaseo では、メソッドを await し、async for でイベントを反復処理します。

リクエストの制御とエラー

TypeScript、Python、Java では、再試行のデフォルトは 0 で、GET と HEAD のリクエストにのみ適用されます。有料の送信、書き込み、ストリーミングのリクエストは再試行されません。
withOptions(...) は、それらの制御をすべてのリソース、ストリーム、メディアの呼び出しに適用した新しいクライアントを返します。元のクライアントは変更されません。再試行は Retry-After に従います。timeoutMs にはレスポンス本文の読み込みも含まれます。responseMetadata(result) は、Gateway のリクエスト ID とダッシュボードのトレース URL を返します。HTTP エラーは PhaseoHttpError で、HTTP の status、API エラーの code、requestId、traceUrl、再試行までの待ち時間、本文、headers を含みます。
各言語の完全なエラーハンドラーは使い方にあります。

ラッパーのないエンドポイントを呼び出す

各 SDK には、Phaseo の OpenAPI 仕様から生成されたクライアントも含まれています。 生成された操作はラッパーメソッドより低レベルです。ラッパーがある場合はそちらを使ってください。

出力を解析し、ストリームを集める

これらのヘルパーは TypeScript と Python にあります。responses.parse(request, schema) は、完了した JSON レスポンスを検証します。schema は、TypeScript では Zod 互換のパーサー、Python では Pydantic モデルです。リクエストにも構造化出力の形式を設定してください。パーサーは検証しか行いません。 collectStream(client.streamResponses(request))(TypeScript)、または collect_stream と collect_async_stream(Python)は、ストリーミングされたテキストと使用量を集めます。

呼び出す前にモデルを確認する

checkModelCapabilities / check_model_capabilities(TypeScript と Python)は、有効なプロバイダーのオファー 1 つについて、公表されている機能とスカラーの制約(inputTypes、outputTypes、endpoints、parameters、parameterValues、Python ではスネークケースの名前)を確認します。モデルを変更したりパラメーターを削除したりすることはなく、実際のプロバイダーがリクエストを受け付けることを保証するものでもありません。メタデータがない場合の扱いは異なり、TypeScript は不明として報告し、Python はチェックを失敗させます。 モデルの選択画面やパラメーターのエディターには、ライブのエンドポイントのメタデータを使います。
各パラメーターは supported、partial、unsupported、unknown のいずれかとして返され、該当するプロバイダーのルートと、インラインで強調表示できる制約の問題も含まれます。これらのチェックは明示的な呼び出しで、生成リクエストに照会を追加するものではありません。各 SDK のメソッドはモデルにあります。

ネットワークなしでテストする

@phaseo/sdk/testing から createMockTransport と jobFixtures をインポートし、モックの fetchImpl をクライアントに渡します。フィクスチャは厳密で順序付きです。予期しない呼び出しはローカルで失敗し、ネットワークには届きません。期待したリクエストがすべて行われたかを確認するには mock.assertDone() を呼び出します。

ルームからコードをエクスポートする

Phaseo のルームでリクエストを送信した後、コードを取得 でそのモデルと設定を TypeScript または Python としてエクスポートできます。リクエスト ID がある場合は、リクエストを表示 でダッシュボードのトレースを開けます。エクスポートしたコードは、PHASEO_API_KEY を設定したサーバーで実行してください。
最終更新日 2026年11月5日