アプリケーションを認証する

このページの実装ガイドでは、ブラウザでアクセストークンを使用し、信頼されたサーバーで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キーを絶対に同梱しないでください。ユーザーがそれを抽出し、あなたのアカウントでリクエストを行う可能性があります。代わりに、サーバーで短期間有効なアクセストークンを生成し、そのトークンをブラウザに返してください。

前提条件

アクセストークンを実装する前に:

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

利用可能なグラント

アクセストークンは、グラントによる細かい権限管理をサポートします。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}'

import { CartesiaClient } from "@cartesia/cartesia-js";

const client = new CartesiaClient({ apiKey: "YOUR_API_KEY" });

// TTS and STT access
await client.auth.accessToken({
  grants: {
    tts: true,
    stt: true
  },
  expires_in: 60
});

from cartesia import Cartesia

client = Cartesia(
  token="YOUR_API_KEY"
)

# TTS and STT access
response = client.auth.access_token(
  grants={"tts": True, "stt": True}, # Grant both permissions
  expires_in=60 # Token expires in 60 seconds
)

# The response will contain the access token
print(f"Access Token: {response.token}")

// TTS and STT access
const response = await fetch("https://api.cartesia.ai/access-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cartesia-Version": "2026-03-01",
    Authorization: "Bearer <your_api_key>",
  },
  body: JSON.stringify({
    grants: { tts: true, stt: true },
    expires_in: 60, // 1 minute
  }),
});

const { token } = await response.json();

詳細な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 に表示したりしない

追加リソース

APIリファレンス - アクセストークン生成エンドポイントのドキュメント

はじめに

Text-to-Speech

Speech-to-Text

ツール

連携

エンタープライズ

アプリケーションを認証する

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

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

前提条件

利用可能なグラント

実装ガイド

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

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

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

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

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

サーバー側

クライアント側

追加リソース

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

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

​前提条件

​利用可能なグラント

​実装ガイド

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

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

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

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

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

​サーバー側

​クライアント側

​追加リソース

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

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

前提条件

利用可能なグラント

実装ガイド

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

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

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

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

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

サーバー側

クライアント側

追加リソース