「LLM APIを個人アプリに組み込む」ストリーミング表示とAPIキーの守り方

自分のアプリに AI の返答を出したい。そのとき最初に決めるのは「APIキーをどこに置くか」と「返答をどう画面に流すか」の2つです。Claude API と Cloudflare Workers を例に、キーをブラウザに渡さない中継と、文字が少しずつ出てくる表示を作ります。

完成形:ブラウザ → 自分の中継 → LLM API

作るのは、次の3つがつながった形です。

ブラウザ(入力欄と表示) │ POST /api/chat { "message": "…" } ← キーは持たない ▼ 自分の中継(Cloudflare Workers) │ POST https://api.anthropic.com/v1/messages ← ここで APIキーを付ける ▼ Claude API → 返答を少しずつ(SSE)返す → 中継がそのまま流す → ブラウザが表示

ブラウザから LLM API を直接呼ばないのには理由があります。ブラウザに届いた JavaScript は、誰でも開発者ツールで読めます。そこに APIキーが入っていれば、アプリを開いた人全員にキーを配っているのと同じです。そのキーで使われた分の料金は、あなたに請求されます。

Anthropic の公式 TypeScript SDK も、ブラウザでの利用を既定で無効にしています。README には、秘密の認証情報を露出させないため、と理由が書かれています。有効にするオプションの名前は dangerouslyAllowBrowser です(2026年11月17日確認)。名前がそのまま警告になっています。

もう1つの「少しずつ返す」がストリーミングです。LLM の返答は、全文ができあがるまで数秒から数十秒かかります。全文を待ってから表示すると、その間、画面は止まったままです。できた分から流せば、最初の文字は早く出ます。公式ドキュメントも、長い返答や大きな max_tokens を使うリクエストにはストリーミングを使うよう勧めています。途中で接続が切られる失敗を避けるためです。

この記事では Claude API を例にしますが、「キーは中継に置く」「返答は流す」という形は、ほかの LLM API でも同じです。

準備:必要なものと、今回使うバージョン

必要なもの内容
Claude API のキーClaude Console で作る。キーは開発用と本番用で分ける(公式のベストプラクティス)
API のバージョン指定リクエストのヘッダーに anthropic-version: 2026-10-21(公式ドキュメントの例と同じ値)
モデル例では claude-haiku-5-5。現行でいちばん速く、料金も低いモデル。品質が足りなければ claude-sonnet-5-5 に変える
中継を置く場所Cloudflare Workers。キーは Workers の secret に登録する

出典:Claude API ドキュメント「Streaming messages」「Models overview」、Cloudflare Workers ドキュメント「Secrets」(2026年11月17日に確認)

料金は入力と出力のトークン数(文字を細かく区切った単位)で決まります。公式のモデル一覧では、100万トークンあたり Claude Haiku 5.5 が入力 0.10ドルから・出力 0.50ドルから、Claude Sonnet 5.5 が入力 2ドル・出力 10ドルです(2026年11月17日確認)。出力のほうが高いので、あとで出てくる max_tokens の上限が料金の上限に直結します。

Workers そのものの始め方は「Cloudflare Workersで静的サイトと小さなAPIを公開する」に書きました。この記事は、そこに /api/chat を1つ足す話です。

APIキーを secret に登録する

キーはコードにも設定ファイルにも書きません。Workers の secret に登録します。

ターミナル(本番用のキーを登録)
npx wrangler secret put ANTHROPIC_API_KEY

コマンドを実行すると値を聞かれるので、そこにキーを貼ります。Cloudflare のドキュメントによると、登録した値はそのあと wrangler にもダッシュボードにも表示されません。同じドキュメントは、wrangler の設定ファイルの vars に秘密の値を書かないよう注意しています。設定ファイルは Git に入るからです。

手元で動かすときは、設定ファイルと同じフォルダに .dev.vars を作り、開発用のキーを書きます。

.dev.vars(手元だけ。Git に入れない)
ANTHROPIC_API_KEY="開発用のキー"
.gitignore
.dev.vars*
.env*
⚠️ 注意
.gitignore への追加は、.dev.vars を作る前に済ませます。一度コミットしたキーは、ファイルを消しても Git の履歴に残ります。Anthropic の案内では、公開リポジトリに漏れた Claude API のキーは GitHub との連携で検出され、自動で無効化されます。ただし、それは最後の網です。漏らしたと気づいたら、Console ですぐにキーを削除して作り直します。

AI にコードを書かせているときも同じです。会話にキーを貼らない。.dev.vars の中身を読ませない。CLAUDE.md に「秘密の値をコードやログに出さない」と書いておくと、毎回言わずに済みます。

中継を書く:キーを付けて、返答をそのまま流す

中継の仕事は4つです。入力を確かめる。キーを付けて API を呼ぶ。返ってきたストリームをそのままブラウザへ渡す。失敗したら中身を隠してエラーを返す。

worker/index.ts
interface Env {
  ANTHROPIC_API_KEY: string; // secret に登録した値が入る
}

const MAX_INPUT = 2000; // 1回に受け付ける文字数の上限

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname !== '/api/chat') return new Response('Not found', { status: 404 });
    if (request.method !== 'POST') return new Response('Method not allowed', { status: 405 });

    // ほかのサイトのページからの呼び出しを断る
    const origin = request.headers.get('origin');
    if (origin && origin !== url.origin) return new Response('Forbidden', { status: 403 });

    // 受け取るのは message だけ。型と長さを確かめる
    let message: unknown;
    try {
      ({ message } = (await request.json()) as { message?: unknown });
    } catch {
      return new Response('Bad request', { status: 400 });
    }
    if (typeof message !== 'string' || !message.trim() || message.length > MAX_INPUT) {
      return new Response('Bad request', { status: 400 });
    }

    // モデル・上限・システムプロンプトは、ここ(サーバー側)で決める
    const upstream = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        'x-api-key': env.ANTHROPIC_API_KEY,
        'anthropic-version': '2026-10-21',
      },
      body: JSON.stringify({
        model: 'claude-haiku-5-5',
        max_tokens: 1024,
        stream: true,
        system: 'あなたは料理アプリの案内役です。料理の質問にだけ、短く答えてください。',
        messages: [{ role: 'user', content: message }],
      }),
    });

    // API のエラーの中身は、利用者に見せない
    if (!upstream.ok || !upstream.body) {
      console.error('upstream error', upstream.status);
      return new Response('Upstream error', { status: 502 });
    }

    // 届いた分から、そのままブラウザへ流す
    return new Response(upstream.body, {
      headers: {
        'content-type': 'text/event-stream; charset=utf-8',
        'cache-control': 'no-store',
      },
    });
  },
};

ストリーミングにするための変更は、リクエストの stream: true と、最後の new Response(upstream.body, …) だけです。Cloudflare のドキュメントによると、Workers は返答の全体を用意してから返す必要がなく、ReadableStream に入ってきたデータは届いた順にクライアントへ流れます。中継が全文をためこむことはありません。

なぜ、ブラウザから受け取るのを message だけにするのか

❌ やりがちなNG ブラウザが送ってきた内容を、そのまま API に渡す
const body = await request.text(); // model も max_tokens も、相手の言いなり
const upstream = await fetch('https://api.anthropic.com/v1/messages', { /* … */ body });
✅ 正しい書き方 受け取るのは質問の文字列だけ。残りはサーバー側で組み立てる
body: JSON.stringify({
  model: 'claude-haiku-5-5',   // 固定
  max_tokens: 1024,            // 固定
  stream: true,
  system: '…',                 // 固定
  messages: [{ role: 'user', content: message }],
}),

NG の形だと、キーは隠せていても、中継が「誰でも好きなモデルを好きなだけ呼べる窓口」になります。いちばん高いモデルで、最大の長さの返答を、何度でも頼めてしまう。キーを守るというのは、文字列を隠すことだけではなく、そのキーでできることを絞ることまで含みます。

ブラウザ側:届いた断片をつないで表示する

stream: true を付けると、返答は SSE(Server-Sent Events。サーバーが1本の接続にイベントを書き足していく形式)で届きます。公式ドキュメントによると、イベントは次の順で流れてきます。

  1. message_start中身が空のメッセージ。ここから始まります。
  2. content_block_start → content_block_delta(何度も)→ content_block_stop返答の本体。文字は content_block_delta に少しずつ入って届きます。
  3. message_delta終わった理由や、使ったトークン数などの更新。
  4. message_stop終わりの合図。

合間に ping が入ることがあり、混雑時などには error イベントが流れることもあります。文字が入っているイベントは、こういう形です。

届くデータ(公式ドキュメントの例)
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

イベントとイベントの間は空行で区切られます。ブラウザ側は、data: の行を JSON として読み、text_delta の text を表示に足していけば済みます。

chat.js(ブラウザ側)
const output = document.querySelector('#answer');
let controller;

async function ask(message) {
  controller = new AbortController(); // 「止める」ボタンで controller.abort()
  output.textContent = '';

  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ message }),
    signal: controller.signal,
  });
  if (!res.ok) { output.textContent = 'うまく答えられませんでした。少し待ってからもう一度お試しください。'; return; }

  // バイト列 → 文字列。文字の途中で切れた分は TextDecoderStream が持ち越してくれる
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;

    // 空行までそろったイベントだけを取り出す。残りは次の read を待つ
    let end;
    while ((end = buffer.indexOf('\n\n')) !== -1) {
      const block = buffer.slice(0, end);
      buffer = buffer.slice(end + 2);
      const line = block.split('\n').find((l) => l.startsWith('data:'));
      if (!line) continue;
      const ev = JSON.parse(line.slice(5));

      if (ev.type === 'content_block_delta' && ev.delta.type === 'text_delta') {
        output.textContent += ev.delta.text; // innerHTML は使わない
      } else if (ev.type === 'error') {
        output.textContent += '\n(途中で止まりました。もう一度お試しください)';
      }
      // それ以外のイベントは無視する
    }
  }
}

このコードには、理由のある書き方が3つあります。

1つ目は buffer。reader.read() が返す1回分は、イベントの切れ目とそろっていません。JSON の途中で切れた断片が届くので、空行が来るまでためてから読みます。

2つ目は delta.type の確認。現行のモデルは、返答の前に考える過程(thinking)のブロックを流すことがあり、そこにも content_block_delta が使われます。text_delta だけを拾えば、表示したい文字だけが残ります。公式ドキュメントは、今後イベントの種類が増えることがあるので、知らない種類は無視できるようにしておくよう求めています。

3つ目は textContent。LLM の返答には、利用者が入力した文字列がそのまま含まれることがあります。innerHTML に足すと、返答に混ざったタグがページの中で動きます。

Node.js などのサーバーで公式の SDK を使うなら、この読み取りは SDK がやってくれます。自分で書くのは、ブラウザのように SDK を置けない場所だけです。

確かめる:断片が途中で切れても、正しくつながるか

バッファの必要性は、動かすとすぐ分かります。下のデモは、SSE の形をした見本のデータを、わざと中途半端な位置で切ってブラウザの ReadableStream に流します。「バッファあり」は上のコードと同じ読み方、「バッファなし」は届いた断片をその場で読もうとするやり方です。

API は呼んでいません。返答の文章は、このページに書いてある見本です。

▶ Live Demo — 途中で切れた SSE を、バッファでつないで表示する

「流す」を押すと始まります。

下の黒い欄が、届いた生のデータです。オレンジの線が断片の切れ目で、JSON の途中や、日本語1文字の途中(日本語は UTF-8 で1文字が3バイト)で切れているのが分かります。「バッファあり」は、1回に届く量をいくつにしても全文がそろいます。「バッファなし」は、量を小さくするほど文章が欠けます。

本番の API につないだあとは、次の3つを確かめます。

  • ブラウザの開発者ツールのネットワーク欄で、/api/chat の応答が少しずつ増えていくこと
  • 同じ欄で、リクエストのヘッダーにも、読み込まれた JavaScript の中にも、APIキーが出てこないこと
  • 2,000文字を超える入力や、message 以外の項目を送っても、中継が 400 を返すか無視すること

つまずきやすい点:キーを隠したあとに残る穴

中継そのものを連打される

キーを隠しても、/api/chat の URL は誰でも呼べます。コードの中の Origin の確認は、ほかのサイトのページに埋め込まれるのを防ぐだけで、コマンドラインから直接呼ばれるのは防げません。備えは重ねます。

  • 入力の長さと max_tokens を固定する:1回の呼び出しでかかる料金に上限ができます。今回のコードでは 2,000文字と 1,024トークンです。
  • 回数を制限する:Cloudflare Workers には、Worker の中から使えるレート制限の機能(Rate Limiting の binding)があります。ドキュメントによると、制限はアクセスを受けた Cloudflare の拠点ごとに数えられ、厳密な上限にはなりません。キーには IP アドレスではなく、利用者の ID のような安定した値を使うよう勧められています。ログインのあるアプリなら、利用者ごとに数えます。
  • 利用額の上限を決める:Claude Console の Spend limits で、月の利用額に自分で上限を設定できます。公式ドキュメントによると、設定した額に達したあとのリクエストは HTTP 400 で断られます。アプリは止まりますが、請求は止まります。
📌 ポイント
3つのうち、最初に設定するのは利用額の上限です。コードに穴があっても、キーが漏れても、被害の天井が決まります。個人開発では、止まるアプリより、止まらない請求のほうが困ります。

ステータス 200 のあとでエラーが来る

ストリーミングでは、返答が始まった時点で HTTP のステータスは 200 に決まっています。公式ドキュメントによると、そのあとで起きた問題は、ストリームの中の error イベントとして届きます。混雑時の overloaded_error がその例です。res.ok だけを見ていると、途中で止まった返答を「完了」として扱ってしまいます。error イベントと、message_stop が来ないまま接続が終わった場合の両方で、「途中で止まった」と表示します。

システムプロンプトは秘密の置き場所ではない

システムプロンプトを中継に置くと、ブラウザからは見えなくなります。ただ、聞き方しだいで LLM が中身を話してしまうことはあります。合言葉やほかのサービスのキーを、システムプロンプトに書かないでください。

ブラウザから直接呼んだときの CORS エラー

試しにブラウザから API を直接呼ぶと、組織の設定によっては CORS requests are not allowed for this Organization で始まる 401 が返ります。公式ドキュメントはこの場合について、ブラウザ側の変更では直らないので自分のバックエンドから送るように、と書いています。この記事の形にすれば解消します。

まとめ

  • LLM の APIキーはブラウザに置かない。自分の中継(Cloudflare Workers など)に置き、ブラウザは中継を呼ぶ。
  • キーは wrangler secret put で登録し、手元では .dev.vars を使う。どちらも Git に入れない。
  • 中継がブラウザから受け取るのは質問の文字列だけにし、モデル・max_tokens・システムプロンプトはサーバー側で固定する。
  • Claude API は stream: true で SSE を返す。文字は content_block_delta の text_delta に入って届く。
  • 届く断片はイベントの切れ目とそろわない。空行までバッファにためてから JSON として読む。
  • 表示には textContent を使い、知らない種類のイベントは無視する。途中の error イベントも扱う。
  • 入力の長さの上限、回数の制限、Console の利用額の上限を重ねる。最初に設定するのは利用額の上限。

参考・出典

料金・モデル名・API のバージョンは確認日の情報です。中継のコードは公式ドキュメントの書き方に沿った例で、実際の API につないだ動作確認はしていません。最新の情報は各公式サイトでご確認ください。