コアガイド
信頼性の高い TokenLab 統合の構築
コスト、リトライ、APIキー、リクエスト記録を適切に管理する
優れた統合とは、価格やモデルの選択肢を可視化し、一般的なネットワーク障害に耐え、ブラウザ上で API キーを一切露出させないものです。以下のプラクティスは、チャット、画像、動画、音声、およびその他の TokenLab API 全般に適用されます。
最新のデータに基づいたモデルの選択
モデル名、機能、価格は変更される可能性があります。コードやドキュメントに固定のリストを保持するのではなく、Models API またはモデルページを参照してください。
新しいユースケースの場合:
- プロダクトが必要とする機能でモデルをフィルタリングします。
- 現在の TokenLab 価格を比較します。
- 代表的なユーザーリクエストを用いて、少数のセットでテストします。
- 各リクエストでモデル ID を明示的に指定します。
モデルを無断で切り替えないでください。モデルの変更により、出力品質、価格、コンテキスト長、利用可能なツール、またはメディアサポートが変化する可能性があります。
コストに上限を設ける
テキストモデルの場合、プロダクトで実際に使用できる長さにまで出力を制限してください。パラメータ名は API やモデルによって異なるため、max_tokens や max_output_tokens を送信する前にモデルページを確認してください。
短い指示が自動的に優れているわけではありませんが、重複したコンテキストや繰り返される定型文は常にインプットトークンを増加させます。安定した指示は簡潔に保ち、次の回答に必要な履歴のみを送信してください。
画像、動画、音楽、3D、および Worlds のリクエストでは、コストは多くの場合、出力数、期間、解像度、またはその他のメディアオプションに依存します。API が見積もりを提供できる場合は、高額な生成をユーザーが確定する前に、現在の見積もりを表示してください。
長いテキスト応答のストリーミング
ストリーミングを行うと、回答が到着するたびに表示されるため、ユーザーが完全な応答を待つ必要がなくなります。ただし、トークンコストが削減されるわけではありません。
クライアント設定と完了チェックを含む完全な例については、ストリーミング を参照してください。
切断が発生した場合は、不完全な回答として処理してください。部分的な出力を正常に完了したものとして提示したり、副作用や課金が発生する可能性がある状況で自動的にリクエストを繰り返したりしないでください。
安全な場合のみリトライする
429 応答に対しては、Retry-After または retry_after に従ってリトライしてください。一時的な 5xx 応答に対しては、短い指数バックオフが適切です。認証、バリデーション、残高不足、コンテキスト長エラーについては、アプリケーション側またはユーザー側での修正が必要であり、同じリクエストを再送しても解決しません。
Retry-After を尊重し、SDK の重複リトライを無効にする制限付きリトライの例については、レート制限 を参照してください。
リトライ回数と合計時間制限を設定してください。メディア作成の場合は、返されたタスク ID を保存してください。Retry safely with an idempotency key に記載されているリクエストについては、Idempotency-Key を送信し、タイムアウト後のリトライで同じリクエストが二重に実行・課金されないようにしてください。
API キーをサーバーに保持する
TokenLab API キーをブラウザの JavaScript、モバイルアプリケーションのバンドル、公開リポジトリ、またはクライアントから見えるログに埋め込まないでください。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)開発環境、本番環境、および独立したアプリケーションごとに個別の API キーを使用してください。各キーには、必要なモデルと支出制限のみを割り当ててください。キーが漏洩した可能性がある場合は、直ちに失効させてください。
有用なリクエスト記録を保持する
ユーザーのアクションと使用状況やサポート記録を紐付けられる識別子を保存してください:
- API リクエスト用の
request_id - 非同期生成用の
task_id - 返却される場合の
billing_transaction_id - モデル ID およびエンドポイント
- 独自のユーザー ID、プロジェクト ID、またはジョブ ID
API キー、管理トークン、完全なプライベートプロンプト、プライベートメディア、または署名付き URL をログに記録しないでください。Console および Management API の使用記録が請求額の根拠となります。モデルの応答トークン数だけでは、最終的な請求額を正確に表せない場合があります。
非同期処理を前提に設計する
画像、動画、音楽、3D、および Worlds API は、結果が準備できる前に応答を返す場合があります。タスク ID を保存し、GET /v1/tasks/{id} をポーリングして、completed または failed になるまで待機してください。ステータスが failed であることは、生成そのものが失敗したことを意味するとは限りません。
キャンセル、タイムアウト、および重複リクエストの処理については、非同期ジョブとポーリング を参照してください。
リリース前に
- 出荷するモデルと API 形式を正確に使用して、代表的なリクエストを実行してください。
- 成功時と一般的なエラー応答の両方を確認してください。
- プロダクトに表示される価格が、現在の TokenLab 価格と一致していることを確認してください。
- リフレッシュ、ネットワークタイムアウト、および繰り返しのクリックに対して安全であることを確認してください。
- ユーザーに見える結果を、その Request ID に遡って追跡できるようにしてください。