目次
Perplexity は Agent API の公式ドキュメント(docs.perplexity.ai/docs/agent-api/prompt-caching)に Prompt Caching の専用リファレンスページを掲載し、プロンプトプレフィックス再利用時の Cache read / Cache write 課金ルール、prompt_cache_key によるリクエストルーティング、および implicit / explicit モードでのキャッシュ制御方法を解説しています。Perplexity はこれに先立ち 2026年8月に Agent API のプリセット(presets)向けに安定したプロンプトキャッシュキーの自動適用を導入しており(プリセットを頻繁に利用するアプリで約 5% のコスト削減が可能と案内)、関連 API 情報は当サイトの Perplexity Monitor API ドキュメントと料金表、Perplexity Decisions API アップデート、および Perplexity 特集ページ もあわせて参照できます。
デフォルトのキャッシュ動作と Cache read / write 課金ルール
デフォルトでは、Agent API がシステム指示(system instructions)と最新メッセージにキャッシュブレークポイントを自動配置し、モデルプロバイダ側の自動キャッシュも併用されるため、単一のエージェント実行(agent run)であれば設定変更なしでキャッシュの恩恵を受けられます。レスポンスの usage には以下の内訳が出力されます。
キャッシュ読み取り(input_tokens_details.cache_read_input_tokens):キャッシュから読み取られた入力トークン数で、各モデルの Cache read 単価が適用されます。OpenAI 互換の cached_tokens にも同じ値が報告され、読み取りコストは cost.cache_read_cost に記録されます。
キャッシュ書き込み(input_tokens_details.cache_creation_input_tokens):プロンプトキャッシュへ新規に書き込まれた入力トークン数で、各モデルの Cache write 単価が適用されます(費用は cost.cache_creation_cost に記録)。各モデルの単価は Agent API Models 料金表に掲載されており、Cache write 列がないモデルやダッシュ(—)表記のモデルは通常の Input 単価で課金されます。
書き込み単価が高いモデルでのコスト注意点:公式例に挙げられている openai/gpt-6.1-sol(Perplexity の料金表では Input が $2.00/1M[≤272k]・$4.00/1M[>272k]、Cache write が $2.50/1M[≤272k]・$5.00/1M[>272k]、Cache read が 95% off input)のように、Cache write 単価が通常の入力単価を上回るモデルでは、書き込んだプレフィックスが後続リクエストで読み返されない限り、キャッシュなしのリクエストより割高になります。
Agent API Models リファレンスと料金計算機には openai/gpt-6.2-sol と openai/gpt-6.2-astra およびそのデフォルト処理料金が掲載されており、キャッシュの読み取りと書き込みはその表のキャッシュ料金で課金され(入力料金は使わない)、この 2 モデルの Perplexity チャネル料金は OpenAI、「GPT-6.2 Astra」と「GPT-6.2 Sol」を正式発表――ChatGPT Work・Codex・API で提供開始、料金表も公開 でも確認できます。
prompt_cache_key によるリクエスト間のプレフィックス再利用
リトライやマルチターン会話で同じプレフィックスを共有するリクエストには、同一の prompt_cache_key を送信してキャッシュ親和性に基づくルーティングを行います。
アカウント単位の分離とモデル選択:prompt_cache_key はアカウント単位でスコープが分離されており、他アカウントが同じキー文字列を指定してもキャッシュは共有されません。また、キーの指定によって処理担当モデルが変わることはありません。
ワークロードごとのキー設計とエフォート設定:ドキュメント単位やプロンプトテンプレート単位など、プレフィックスを共有するワークロードごとに 1 つのキーを割り当てます。推論エフォート(effort levels)ごとに共有システムプロンプトとツール用のデフォルトキーが設定されますが、明示的に送信した prompt_cache_key が優先されます。
プレフィックス配置順序と会話の継続:キャッシュ読み取りにはプレフィックスの完全一致が必要なため、固定要素(指示文、参照文書、スキーマ)をプロンプトの先頭に置き、可変要素を末尾に配置します。会話を継続する際は、同じキーで新しいターンを追記して再送するか、previous_response_id を渡して前のターンをそのまま引き継ぎます。
implicit / explicit モードによるブレークポイント制御
prompt_cache_options.mode と input_text パート内の prompt_cache_breakpoint を組み合わせることで、キャッシュ境界を明示的に制御できます。
implicit モード(デフォルト):Agent API がデフォルトのブレークポイントを配置し、プロバイダ側の自動キャッシュも有効になります。input_text パートに prompt_cache_breakpoint を指定した場合はデフォルトのブレークポイントが置き換えられ、1 リクエストあたり最大 3 個まで設定可能です。
explicit モード:デフォルトのブレークポイントと自動キャッシュを無効化し、明示的にマークした input_text パートのみをキャッシュします(1 リクエストあたり最大 4 個まで)。プレフィックスを再利用しない単発リクエストでは、マークを付けずに "prompt_cache_options": {"mode": "explicit"} を送信することでキャッシュ書き込み課金を回避できます。
ブレークポイントの引き継ぎ・TTL・SDK 実装上の注意:再利用したいプレフィックス末尾の input_text にマークを付けると、それより前のシステム指示やメッセージ全体がまとめてキャッシュされます。マークはレスポンスとともに保存されて previous_response_id 継続時にも維持され、モード上限を超えた場合は最新のマークが優先されます(上限超過や input_text 以外への指定は HTTP 400 エラー)。なお、prompt_cache_options.ttl は OpenAI 互換のために受理されるものの無視され、プロバイダ既定のキャッシュ保持期間が適用されます(OpenAI の 12 時間 TTL 設定 とは仕様が異なります)。エンドポイント https://api.perplexity.ai/v1/agent を呼び出す際、公式の Python および TypeScript サンプルでは prompt_cache_options と prompt_cache_breakpoint が SDK の型定義に未収録のため、Python では extra_body 経由、TypeScript では @ts-expect-error を付けて渡すよう案内されています。
