Streaming Claude API：主要機能をわかりやすく解説

Claude を速く感じさせたいなら、ストリーミングをオンにしましょう。 1 つの完全な返信を 15〜25 秒待つ代わりに、ユーザーは最初のトークンをおよそ 300〜800 ms で目にできることが多くなります。

手短にまとめると次のとおりです。

• 返信を生成されるそばから表示したいときは、私なら SSE ストリーミングを使います
• API キーを守るために、私なら Claude の呼び出しをバックエンドプロキシの背後に置きます
• UX と支出をコントロールするために、私なら TTFT（time to first token）、max_tokens、切断を監視します
• 私なら、ストリーミングされるイベントを順番に解析します：message_start、コンテンツブロック系イベント、message_delta、そして message_stop
• 私なら、コンテンツブロックが終わるまでツールの JSON 断片をバッファリングします
• 私なら、接続の切断に備えます。Claude はストリームをネイティブに再開しないからです

いくつかの数値が目を引きます。

• Haiku 4.5： TTFT は約 410 ms
• Sonnet 4.6： TTFT は約 720 ms
• Opus 4.7： TTFT は約 980 ms
• デフォルトのプロキシタイムアウト 30〜60 秒は、長い出力を途中で打ち切ることがある
• より長い読み取りタイムアウト 120〜300 秒が必要になることが多い
• バッチジョブは標準のトークン単価より 50% 安くできる

平たく言えば、ストリーミングが変えるのは_配信_であって、モデルそのものではありません。Claude API は、ライブ接続を通じて小さなイベントのかたまりでテキストを送り、私のアプリが最終的な回答を画面上で組み立て直します。チャット、コパイロット、アシスタントにとって、これはたいてい、より良い体感、アイドルタイムアウト問題の減少、そしてクライアント側とバックエンド側での作業の増加を意味します。

最も重要なのは次の点です。

だからもし私がこれを構築するなら、ストリーミングを単なる API のフラグではなく、UX とインフラの選択として捉えます。

Building with Claude API - Part 4 - Response Streaming

Claude API のストリーミングはプロトコルレベルでどう動くか

ストリーミングをオンにしても、モデルそのものは変わりません。変わるのは出力の配信方法です。1 つの完全な応答を待つ代わりに、Claude は準備でき次第、小さなかたまりを送ります。

どのエンドポイントとリクエスト設定でストリーミングが有効になるか

ストリーミングは、通常のリクエストと同じ Claude Messages API エンドポイント /v1/messages を使います。唯一の違いは、リクエストボディに "stream": true を追加することです ^[1][3]。このフラグにより、接続は標準のリクエスト・レスポンス方式から、サーバーが生成されたかたまりをプッシュする Server-Sent Events (SSE) へと切り替わります。

公式の Python と TypeScript の SDK には、イベント解析とメッセージの組み立てを代わりに行ってくれるストリームヘルパーが含まれています。ストリームが終わると、Python では .get_final_message()、TypeScript では .finalMessage() を呼ぶことで、完成した応答がトークン数と停止理由とともに返されます ^[1][4]。

これらの設定でストリームが始まります。次の要素は、接続を通じて返ってくるイベントの流れです。

ストリーム中にどんなイベントが届くか

ストリームは、名前付きイベントの決まった順序に従います。各イベントは、クライアントがフル応答を正しく組み立て直すために必要なデータを運びます。

これが、クライアントがバッファリングしリアルタイムで表示するデータです。プレーンテキスト出力の場合は、イベントが届くたびに各 text_delta をローカルバッファに追記します。そうやってフル応答の文字列が少しずつ組み上がっていきます。ツール呼び出しの入力は少し違った動きをします。input_json_delta の断片として届くので、まずバッファリングし、content_block_stop の後で初めて解析すべきです ^[1][6]。

Claude のストリーミングで APIMart が役立つのはどんなときか

Claude のストリーミングがマルチモデルアプリの中に組み込まれているなら、APIMart は Claude へのアクセスとストリーミングを統一 LLM API経由でルーティングする一元的な場所を提供できます。これが最も効いてくるのは、ウェブとモバイルのクライアント全体で同じストリーミングフローを使いたいときです。

ウェブ・モバイルアプリに Claude ストリーミングを追加する方法

SSE、HTTP ストリーミング、WebSocket ラッパー：どれを使うべきか

Claude がストリーミングイベントをどう送るかを理解したら、次のステップはそれらのイベントをウェブとモバイルのクライアントへ届けることです。問いはシンプルです：あなたのアプリにどのトランスポートが最も合うか？

ほとんどのブラウザベースのアプリでは、SSE がデフォルトの選択肢です。多くのプロキシや CDN とうまく動作し、ブラウザのサポート状況もシンプルです。

WebSocket も依然として理にかなう場合があります。アプリが既に双方向のライブ通信に依存しているなら、そのままフィットするかもしれません。しかし標準的なチャットアプリでは、得られる価値以上に可動部品を増やしてしまうことが多いです。

なぜバックエンドプロキシがたいてい最も安全なアーキテクチャなのか

トランスポートを選んだら、ストリーム処理をサーバーの背後に置きましょう。各種モデルの API キーを守るために、Claude のリクエストをバックエンドプロキシの背後に保ちます ^[9][5]。

そのプロキシ層は、次のことを行うのにも適した場所です。

• システムプロンプトを注入する
• ユーザーごとのレート制限を課す
• 最初のトークンと最後のトークンのタイミングをログに記録する

プロキシのバッファリングを止めるために X-Accel-Buffering: no を設定します ^[2][8]。また、クライアントの中断シグナルをストリームに接続します。そうすれば、ユーザーが生成を止めたときにリクエストがすぐにキャンセルされ、誰も読まない応答にトークンを浪費せずに済みます。

もう 1 つの落とし穴：デフォルトのタイムアウト 30〜60 秒は、長い応答を途中で打ち切ることがあります ^[9][2]。本番では、長めの生成向けに約 120〜300 秒の読み取りタイムアウトを使いましょう。

ライブ応答中の良いクライアント側 UX とはどんなものか

ストリームが保護されリレーされたら、仕事は UI へと移ります。ここが、ストリーミングがなめらかに感じられるか、ぎこちなく感じられるかの分かれ目です。

ユーザーがプロンプトを送信したらすぐに、**「Thinking...」**インジケーターやスピナーを表示します。これで最初のトークンまでの遅延をカバーできます。最初の content_block_delta が届いたらすぐに、インジケーターを消してテキストのレンダリングを始めます。

その後、届いた各 text_delta を追記していき、応答がタイプライター効果で現れるようにします。インターフェースがカクつかないよう、requestAnimationFrame で更新をバッチ化し、再レンダリングを起こしすぎないようにします。オートスクロールは生成中の応答を追いかけるべきですが、ユーザーが古い内容を読もうと上へスクロールしたら控えめにするべきです。

Fetch リクエストをキャンセルできるよう、AbortController に接続した**「Stop」**ボタンを常に用意します。これで、すでに画面上にあるテキストを消さずに、ストリームをきれいに終了できるはずです。

接続が切れた場合は、部分的な出力を表示したままにします。復旧のためには、その部分テキストを保持し、継続プロンプトで再開しましょう。Claude は切断されたストリームをネイティブに再開しないからです ^[3][1]。

本番でレイテンシ・コスト・信頼性を管理する方法

ストリームがライブになったら、本番作業は 3 つのコントロールに集約されます：レイテンシ、支出、そして復旧です。

ストリーミングは体感レイテンシをどう変えるか

ここでの主要な UX 指標は Time to First Token (TTFT)、つまり最初の単語が現れるまでの時間です。ストリーミングアプリでは、この最初の目に見えるトークンが、プロダクト全体の体感を形づくります。速く現れればアプリはレスポンシブに感じられ、もたつけばユーザーは気づきます。

ベンチマークは Claude モデル間の明確な差を示しています。Haiku 4.5 は TTFT 約 410 ms に達し、Sonnet 4.6 は 720 ms あたり、Opus 4.7 はおよそ 980 ms です ^[3]。シンプルな原則は、品質基準を満たす中で最も速いモデルを使うことです。

プロンプトサイズも重要です。大きなコンテキストウィンドウは TTFT を 1〜3 秒へと押し上げることがあります ^[5]。ですから、システムプロンプトに余分な指示、古いルール、肥大化した例が含まれているなら、それらを削ることでアプリの体感がずっと機敏になります。

トークン使用量を追跡し USD コストを管理する方法

ストリーミングとバッチはトークンあたりのコストが同じです。変わるのは出力が届くタイミングだけです。トークン数はストリーム自体に含まれます。message_start イベントには usage.input_tokens が含まれ、終わり近くの message_delta イベントには最終的な累積 usage.output_tokens が含まれます ^[1][4]。バックエンドは、請求の正確さを保つために、ストリーム終了後にその最終使用量データを保存すべきです。

すべてのリクエストに max_tokens を設定しましょう。これはハードストップとなり、長い生成がコストを押し上げるのを防ぎます ^[1][11]。また、サーバー側でクライアントの切断も監視すべきです。ユーザーが去ったのに生成が動き続けていると、意味もなくトークンを燃やし続けることになります ^[5][7]。

ライブ出力を必要としないジョブでは、話が変わります。バッチ要約、オフライン処理、夜間のレポート生成などが良い例です。そうしたケースでは、Batch API が通常のトークン単価に対して 50% の割引を提供します ^[5][10]。

Claude 3.5 Sonnet は、標準のストリーミングで入力 100 万トークンあたり約 $3.00、出力 100 万トークンあたり約 $15.00 です ^[8]。Batch API を使えば、非同期のワークロードは半分のコストで済みます。

これらの使用量の数値は、請求とレート制限の監視にも役立ちます。大量リクエストを管理するさらなる戦略については、AI API コストのヒントをご覧ください。

切断されたストリームを防ぎ、安全に復旧する方法

Claude にはサーバー側の再開機能がありません ^[1][3]。ストリームが切れた場合は、部分的な出力を新しいリクエストで送り、Claude に中断地点から続けるよう頼みます。

自然に解消しそうな失敗だけをリトライしましょう。

その後の最後のステップは、どのストリーミング機能が最も重要かを選ぶことです。

まとめ：どの Claude ストリーミング機能が最も重要か

レイテンシ、コスト、信頼性を見てくると、Claude のストリーミングは 3 つに集約されます：体感のレスポンシブさ、明確なイベントシグナル、そして堅実なエラー処理です。

ストリーミングが重要なのは、最初のトークンの配信が Claude を速く、レスポンシブに感じさせるからです。

SSE のイベントフローは、テキストのデルタ、使用量のカウント、エラーのシグナルをリアルタイムで提供します ^[1][3]。

キーを守り、バッファリングを無効化し、切断に対処するために、バックエンドプロキシを使いましょう ^[2][8]。マルチモデルアプリでは、APIMart が Claude のストリーミング、ロギング、請求を一元化できます。

本番では、速い TTFT、使用量の追跡、そしてプロキシの回復力が最も重要です。

FAQ

通常の Claude API レスポンスの代わりに、いつストリーミングを使うべきか？

アプリがユーザー向けのときにストリーミングを使いましょう。生成されたそばからトークンを送るので、応答がほぼ即座に感じられます。そのわずかな変化が、プロダクト全体をより速く、なめらかに感じさせます。

ストリーミングは、リアルタイムチャット、長い回答、ツール呼び出しを伴うエージェントのワークフローに最適です。出力が長引いたりトークン上限が高いときのタイムアウト回避にも役立ちます。

短くシンプルなリクエストや、レイテンシよりスループットが重要なバッチジョブでは、使わないでおきましょう。

Claude のストリームが応答の途中で切断されたらどうすべきか？

Claude のストリームが切断されると、Server-Sent Events は自力で中断地点から再開しません。その部分はあなたのアプリが処理する必要があります。

接続が切れたら、フルリクエストをリトライするか、すでに保存済みの部分的な出力を表示するかのどちらかができます。try/except ブロックで APIConnectionError や APIStatusError をキャッチし、これまで蓄積したコンテンツへの参照を保持しましょう。

より摩擦の少ない形でストリームを続けたいなら、最後のイベント ID を追跡し、その地点からストリームを手動で再生します。

UX を損なわずにストリーミングコストを減らすには？

プロンプトのチューニングと効率的なセッション処理に注力しましょう。max_tokens のハードリミットを設定し、プロンプトを短く保ち、ユーザーが必要なものを得たら生成を止められる早期キャンセルオプションを追加します。

即座のやり取りを必要としないバッチワークロードには、非ストリーミングモードを使いましょう。正確なコスト追跡には、途中のかたまりから推定するのではなく、最後の message_stop イベントを待ちましょう。