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
- Go
- C#
- PHP
- Ruby
- Java
- Rust
音楽、動画、バッチの完了を待つ
待機用のヘルパーは 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 のリクエストにのみ適用されます。有料の送信、書き込み、ストリーミングのリクエストは再試行されません。
- TypeScript
- Python
- Java
- Rust
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 のメソッドはモデルにあります。
ネットワークなしでテストする
- TypeScript
- Python
@phaseo/sdk/testing から createMockTransport と jobFixtures をインポートし、モックの fetchImpl をクライアントに渡します。フィクスチャは厳密で順序付きです。予期しない呼び出しはローカルで失敗し、ネットワークには届きません。期待したリクエストがすべて行われたかを確認するには mock.assertDone() を呼び出します。ルームからコードをエクスポートする
Phaseo のルームでリクエストを送信した後、コードを取得 でそのモデルと設定を TypeScript または Python としてエクスポートできます。リクエスト ID がある場合は、リクエストを表示 でダッシュボードのトレースを開けます。エクスポートしたコードは、PHASEO_API_KEY を設定したサーバーで実行してください。