APIエンドポイント、またはエンドポイントとは、APIがリクエストを受け取り、レスポンスを返すための正確なアドレスです。これは、アプリケーションがデータを要求したりコマンドを実行したりするためにサーバーに接続するポイントです。ElevenLabs社は自社ブログで公開したガイドにおいて、この仕組みをそのインターフェースElevenAPIを用いて詳細に説明しています。
リクエスト、レスポンス、ルート
エンドポイントとは、APIがリクエストを受け取り、レスポンスを返すために使用するデジタル上の場所です。クライアントアプリケーションは、このエンドポイントに紐づけられたURLを通じてサーバーのリソースにアクセスします。各ルートは、ウェブの通信プロトコルであるHTTPメソッドをリソースパスに関連付けます。
やり取りは通常、4つのステップで行われます。まず、クライアントがHTTPメソッド、ヘッダー、場合によってはパラメータとデータ本体を含むHTTPリクエストを送信します。サーバーは認証情報とアクセス権を確認し、その後データベースを照会したりビジネスロジックを実行したりします。次に、構造化データ形式であるJSON形式のペイロードをHTTPステータスコードとともに返します。最後に、クライアントアプリケーションがこのデータを利用します。
API、エンドポイント、URLという用語はしばしば一緒に使われますが、それぞれ異なるものを指します。APIは、2つのアプリケーションが通信するためのルールとデータ契約の集合体です。エンドポイントはその中での正確なエントリーポイントであり、URLはネットワーク上でそのエンドポイントを特定するための完全な文字列アドレスです。1つのAPIには複数のエンドポイントが含まれ、1つのURLにはプロトコル、ドメイン名、パス、クエリパラメータが含まれる場合があります。
REST APIにおいて、GETリクエストはサーバーのリソースを変更せずにデータを読み取り、POSTリクエストはデータを作成したりアクションをトリガーしたりします。PUTまたはPATCHリクエストは既存のレコードを修正し、DELETEは削除するために使用されます。ガイドによると、ElevenAPIは主にGETとPOSTに依存しており、リアルタイム音声のためのストリーミングおよびWebSocketエンドポイントが追加されています。例えば、GETリクエスト https://api.elevenlabs.io/v1/models は、利用可能な音声合成モデルとその機能のリストを取得します。POSTリクエスト https://api.elevenlabs.io/v1/text-to-speech/{voice_id} は、テキストとモデルIDを送信し、ストリーミング音声を返します。
エンドポイントの保護
各リクエストは、秘密鍵をxi-api-keyヘッダーで運びます。これらの長期鍵は安全なサーバーに保管し、ブラウザやモバイルアプリなどのクライアント側コードに決して露出させてはいけません。クライアント側のWebSocket接続の場合、サーバーは使い捨てトークンを生成します。このトークンは15分で期限切れとなり、最初の使用時に消費されます。
ガイドはまた、開発、ステージング、本番環境用に別々の鍵を作成することを推奨しています。各鍵は特定のエンドポイントに制限することができます。例えば、合成を必要としない鍵を音声書き起こしのみに制限するなどです。クレジットのクォータを鍵ごとに設定でき、エンタープライズアカウントでは使用を特定のIPアドレスに制限することができます（この機能はプレビュー版として提供されています）。他のアドレスからのリクエストはHTTP 403エラーで拒否されます。レート制限は、ソースによれば、分単位のクォータではなく、同時実行数（同時生成数）に基づいているとのことです。
テストと監視
最初にエンドポイントをテストすることで、アプリケーションロジックを記述する前に認証と接続性を確認できます。xi-api-keyヘッダーを含む https://api.elevenlabs.io/v1/models へのGETリクエストで、認証情報とネットワークアクセスを検証できます。ガイドによると、このテストではアカウントに課金されるクレジットは消費されません。
また、HTTP 429エラーを監視する必要があります。too_many_concurrent_requestsエラーは、アカウントが契約プランの同時実行制限に達したことを意味します。進行中のリクエストが終了するのを待つか、上位プランにアップグレードする必要があります。一方、system_busyエラーはプラットフォームの一時的な混雑を示しており、通常は再試行で成功します。
