メインコンテンツへスキップ
このページの実装ガイドでは、ブラウザでアクセストークンを使用し、信頼されたサーバーでAPIキーを使用する方法を説明します。
環境推奨される認証理由
ブラウザアプリアクセストークンAPIキーがクライアントコードに露出するのを防ぎます
信頼されたサーバー、スクリプト、またはノートブックAPIキーシンプルで、トークン交換が不要です

​
サーバーサイドアプリ: APIキーを使用する

バックエンドサービス、ジョブ、ローカルスクリプト、ノートブックなどの信頼された環境からは、APIキーを直接使用してください。 Cartesiaは、サーバーサイド認証で X-Api-Key および Authorization ヘッダーの両方を受け入れます。ヘッダー名は大文字小文字を区別しないため、X-API-KEY や authorization でも動作します。 
const ws = new WebSocket("wss://api.cartesia.ai/tts/websocket", {
  headers: {
    // "X-Api-Key": CARTESIA_API_KEY,
    // OR
    // "Authorization": `Bearer ${CARTESIA_API_KEY}`,
  },
});
上記のヘッダーベースのWebSocketの例は、カスタムヘッダーをサポートするサーバーサイドクライアント向けです。ブラウザでは、代わりにアクセストークンとクエリパラメータを使用してください。

​
ブラウザアプリ: アクセストークンを使用する

ブラウザのコードにCartesia APIキーを絶対に同梱しないでください。ユーザーがそれを抽出し、あなたのアカウントでリクエストを行う可能性があります。 代わりに、サーバーで短期間有効なアクセストークンを生成し、そのトークンをブラウザに返してください。

​
前提条件

アクセストークンを実装する前に:
  1. Cartesia API キーでサーバーを設定する
  2. アプリケーションでユーザー認証を実装する
  3. 安全なクライアント-サーバー間通信を確立する

​
利用可能なグラント

アクセストークンは、グラントによる細かい権限管理をサポートします。TTS と STT のグラントはいずれも任意です: TTS グラント: grants: { tts: true } を指定すると、クライアントは次のエンドポイントにアクセスできます:
  • /tts/bytes - チャンクエンコーディングでストリーミングされる同期 TTS 生成
  • /tts/sse - ストリーミング用の Server-Sent Events
  • /tts/websocket - WebSocket ベースのストリーミング
STT グラント: grants: { stt: true } を指定すると、クライアントは次のエンドポイントにアクセスできます:
  • /stt/websocket - WebSocket ベースの音声テキスト変換ストリーミング
  • /stt - バッチ音声テキスト変換処理
  • /audio/transcriptions - OpenAI 互換のトランスクリプション エンドポイント
エージェントグラント: grants: { agent: true } を指定すると、クライアントは以下にアクセスできます:
  • Agents WebSocket呼び出しエンドポイント
1つのトークンで複数のグラントをリクエストできます: 
grants: { tts: true, stt: true, agent: false }

​
実装ガイド

​
1. トークン生成 (サーバー側)

cURL または公式クライアントライブラリを使用して、新しいアクセストークンを生成するリクエストを送信します: 
# TTS and STT access
curl --location 'https://api.cartesia.ai/access-token' \
  -H 'Cartesia-Version: 2026-03-01' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_car_...' \
  -d '{ "grants": {"tts": true, "stt": true}, "expires_in": 60}'
詳細なAPI仕様については、トークンAPIリファレンス を参照してください。

​
2. トークン保存 (クライアント側)

トークンの有効期限に合わせた HTTP-only クッキーを設定するなど、トークンを安全に保存します。クッキーは httpOnly、secure、sameSite: "strict" を設定してください。

​
3. API を使った認証済みリクエストの送信

// Using TTS with access token
const ttsResponse = await fetch("https://api.cartesia.ai/tts/bytes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  // ... request configuration
});

// Using STT with access token
const sttResponse = await fetch("https://api.cartesia.ai/stt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
  body: formData, // multipart/form-data with audio file
});

// Browser WebSocket (access token in query param)
const url = new URL("wss://api.cartesia.ai/tts/websocket");
url.searchParams.set("cartesia_version", "2026-03-01");
url.searchParams.set("access_token", accessToken);

const ws = new WebSocket(url);

​
4. トークンリフレッシュ戦略

各 API 呼び出しの前に、現在のトークンがまだ有効かどうかを確認します。期限切れまたは期限切れ間近の場合は、処理を続行する前にサーバーから新しいトークンをリクエストします。 
async function getValidToken(): Promise<string> {
  if (!token || tokenExpiresAt < Date.now() + 5000) {
    // Token missing or expiring within 5 s — refresh
    const res = await fetch("/api/token");
    const data = await res.json();
    token = data.token;
    tokenExpiresAt = Date.now() + data.expires_in * 1000;
  }
  return token;
}

​
セキュリティのベストプラクティス

​
サーバー側

  • トークンは必ずサーバー側のみで生成する — ブラウザのコードでは絶対に生成しない
  • トークンの有効期間は短く (分単位) する
  • トークンは HTTPS のみで配信する

​
クライアント側

  • トークンは HTTP-only クッキー (ブラウザが自動的に送信するが JavaScript からは読み取れないクッキー) に保存する
  • クッキーの secure および sameSite: "strict" フラグを有効にする
  • トークンを localStorage や sessionStorage に絶対に保存しない
  • トークンをログに出力したり UI に表示したりしない

​
追加リソース