Deepgram Flux からの移行

このガイドでは、Deepgram の Turn-based Audio (Flux) API からの移行を説明します。 Cartesia と Deepgram Flux はどちらも WebSocket 経由でターンベースのイベントを発行するため、Ink への移行は主にフィールド名の変更といくつかの接続パラメーターの更新だけで済みます。

すべての移行ガイド

このガイドには、素の API の説明と SDK コードの両方が含まれています。SDK をインストールするには次のようにします。

pip install cartesia

npm i @cartesia/cartesia-js

すでに Cartesia SDK を使用している場合は、バージョン >=3.2.0 にアップグレードしてください

Ink 2 は現時点で英語のみをサポートしています。
今後数ヶ月のうちに他言語の追加を予定しています。

接続

Deepgram の WebSocket URL と認証ヘッダーを Cartesia のものに置き換えます。

- wss://api.deepgram.com/v2/listen?model=flux-general-en&encoding=linear16&sample_rate=16000
+ wss://api.cartesia.ai/stt/turns/websocket?model=ink-2&encoding=pcm_s16le&sample_rate=16000

- Authorization: Token <DEEPGRAM_API_KEY>
+ Authorization: Bearer <CARTESIA_API_KEY>
+ Cartesia-Version: 2026-03-01

ブラウザでは、WebSocket はリクエストヘッダーをサポートしません。代わりに、API バージョンを cartesia_version クエリパラメーターで渡し、API キーの代わりに短命のアクセストークンを access_token クエリパラメーターで使用してください。 Cartesia SDK でターン検出 WebSocket に接続します:

import os
from cartesia import AsyncCartesia

client = AsyncCartesia(api_key=os.getenv("CARTESIA_API_KEY"))

async with client.stt.auto_finalize.websocket(
    model="ink-2", encoding="pcm_s16le", sample_rate=16000
) as connection:
    ...

import os
from cartesia import Cartesia

client = Cartesia(api_key=os.getenv("CARTESIA_API_KEY"))

with client.stt.auto_finalize.websocket(
    model="ink-2", encoding="pcm_s16le", sample_rate=16000
) as connection:
    ...

import Cartesia from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: process.env.CARTESIA_API_KEY });

const connection = client.stt.autoFinalize.websocket({
  model: "ink-2",
  encoding: "pcm_s16le",
  sample_rate: 16000,
});

// Server-side: Generate access-tokens using your API key
import Cartesia from '@cartesia/cartesia-js';

const client = new Cartesia({ apiKey: process.env.CARTESIA_API_KEY });

export async function GET() {
  const { token } = await client.accessToken.create({
    grants: { stt: true, tts: false, agent: false },
    // How long the token lasts in seconds
    // Allowed values: 0–3600
    expires_in: 3600,
  });
  return Response.json({ token });
}


// Client-side
// 1. Fetch an access token from your server
// 2. Connect to Cartesia via WebSocket
import Cartesia from "@cartesia/cartesia-js";

async function getToken(): Promise<string> {
  const res = await fetch('/replace-with-your-server');
  const { token } = await res.json();
  return token;
}
const audioContext = new AudioContext();

const client = new Cartesia({ token: await getToken() });

const connection = client.stt.autoFinalize.websocket({
  model: "ink-2",
  encoding: "pcm_f32le",
  sample_rate: audioContext.sampleRate,
});

クエリパラメーター

Deepgram Flux	Cartesia Ink	備考
`model=flux-general-en` required	`model=ink-2` required	全オプションは STT モデルを参照してください。
`encoding=linear16`	`encoding=pcm_s16le` required	全オプションはエンコーディングを参照してください。
`sample_rate`	`sample_rate` required	変更なし。
`language_hint`	—	現在は英語のみサポートしています。多言語対応は近日公開予定です！
—	`cartesia_version=2026-03-01` required	詳細は API 規約を参照してください。
`eager_eot_threshold`、`eot_threshold`、`eot_timeout_ms`	`turn_eager_end_threshold`、`turn_end_threshold`、`turn_end_timeout_ms`	しきい値の挙動は Deepgram とは異なります。下記のターン検出を参照してください。
`keyterm`	`keyterm`	キータームプロンプティングを参照してください。
`mip_opt_out`	—	組織によって制御されます。

encoding

Deepgram	Cartesia
`linear16`	`pcm_s16le`
`linear32`	`pcm_s32le`
`mulaw`	`pcm_mulaw`
`alaw`	`pcm_alaw`
非対応	`pcm_f16le`
非対応	`pcm_f32le`
`opus`	非対応
`ogg-opus`	非対応

ターン検出

turn_end_timeout_ms は eot_timeout_ms に直接相当します。 turn_eager_end_threshold と turn_end_threshold は eager_eot_threshold および eot_threshold と同様の機能を提供しますが、方向性が逆になっています。Deepgram では値が高いほど発火前により高い確信度を要求しますが、Cartesia では値が低いほど発火前により高い確信度を要求します。Deepgram の値をそのまま再利用しないでください。各しきい値の挙動、範囲、デフォルト値についてはターン検出の設定を参照してください。

音声の送信

どちらの API も、生の PCM 音声をバイナリ WebSocket フレームとして同じ方法で受け取ります。

Cartesia は次のエンコーディングをサポートしていません: opus、ogg-opus

セッションを閉じるには、JSON エンコードされた WebSocket テキストフレームを送信します:

- { "type": "CloseStream" }
+ { "type": "close" }

Cartesia には、Deepgram の Configure 制御メッセージに相当するものはありません。ターンの終了を設定する必要がないためです。

# Equivalent to 
# deepgram_connection.send_media(audio_chunk)
await connection.send_raw(audio_chunk)

# Equivalent to
# deepgram_connection.send_close_stream()
await connection.send({"type": "close"})

# Equivalent to 
# deepgram_connection.send_media(audio_chunk)
connection.send_raw(audio_chunk)

# Equivalent to
# deepgram_connection.send_close_stream()
connection.send({"type": "close"})

// Equivalent to deepgramConnection.sendMedia(audioChunk)
// @param {ArrayBufferLike} audioChunk - Note: Blob is not accepted
connection.sendRaw(audioChunk);

// Equivalent to
// deepgramConnection.sendCloseStream({ type: "CloseStream" })
connection.send({ type: "close" });

イベントマッピング

Deepgram `type`	Cartesia `type`
`Connected`	`connected`
`Error`	`error`
`TurnInfo`	下記参照

Deepgram はすべてのターンイベントを単一の TurnInfo メッセージに event 判別子付きでラップします。Cartesia はイベントごとに 1 つのメッセージタイプを発行し、その型はトップレベルの type フィールドに含まれます。

Deepgram `TurnInfo.event`	Cartesia `type`	`transcript` を含むか？
`StartOfTurn`	`turn.start`	いいえ（Deepgram: はい）
`Update`	`turn.update`	はい
`EagerEndOfTurn`	`turn.eager_end`	はい
`TurnResumed`	`turn.resume`	いいえ（Deepgram: はい）
`EndOfTurn`	`turn.end`	はい

Deepgram の TurnInfo メッセージ:

{
  "type": "TurnInfo",
  "event": "EndOfTurn",
  "turn_index": 0,
  "transcript": "Hi I need to cancel my subscription please.",
  "words": [...],
  "end_of_turn_confidence": 0.7,
  "audio_window_start": 0.0,
  "audio_window_end": 1.7
}

これは Cartesia の turn.* イベントになります:

{
  "type": "turn.end",
  "transcript": "Hi I need to cancel my subscription please.",
  "request_id": "2ff8af53-4d38-479d-8287-58940f01c701"
}

Deepgram と同様に、transcript はターン内で累積的です。

イベントハンドラー

ハンドラーの分岐構造は変わりません。変わるのはメッセージの形状だけです。

  ws.onmessage = (message) => {
    const data = JSON.parse(message.data);
-   if (data.type !== "TurnInfo") return;
-   switch (data.event) {
-     case "StartOfTurn":    onTurnStart(); break;
-     case "Update":         onTranscriptUpdate(data.transcript); break;
-     case "EagerEndOfTurn": prepareReply(data.transcript); break;
-     case "TurnResumed":    cancelReply(); break;
-     case "EndOfTurn":      finalizeReply(data.transcript); break;
-   }
+   switch (data.type) {
+     case "turn.start":     onTurnStart(); break;
+     case "turn.update":    onTranscriptUpdate(data.transcript); break;
+     case "turn.eager_end": prepareReply(data.transcript); break;
+     case "turn.resume":    cancelReply(); break;
+     case "turn.end":       finalizeReply(data.transcript); break;
+   }
  };

import asyncio
from cartesia.types.stt import STTAutoFinalizeWebsocketResponse

def on_message(message: STTAutoFinalizeWebsocketResponse) -> None:
    if message.type == "turn.start":
        print("StartOfTurn")
    elif message.type == "turn.update":
        print(f"Update: {message.transcript}")
    elif message.type == "turn.eager_end":
        print(f"EagerEndOfTurn: {message.transcript}")
    elif message.type == "turn.resume":
        print("TurnResumed")
    elif message.type == "turn.end":
        print(f"EndOfTurn: {message.transcript}")
    elif message.type == "error":
        print(f"Error: {message.message}")

# Equivalent to
# deepgram_connection.on(EventType.MESSAGE, on_message)
connection.on("event", on_message)

# Equivalent to
# asyncio.create_task(deepgram_connection.start_listening())
recv_task = asyncio.create_task(connection.dispatch_events())

import threading
from cartesia.types.stt import STTAutoFinalizeWebsocketResponse

def on_message(message: STTAutoFinalizeWebsocketResponse) -> None:
    if message.type == "turn.start":
        print("StartOfTurn")
    elif message.type == "turn.update":
        print(f"Update: {message.transcript}")
    elif message.type == "turn.eager_end":
        print(f"EagerEndOfTurn: {message.transcript}")
    elif message.type == "turn.resume":
        print("TurnResumed")
    elif message.type == "turn.end":
        print(f"EndOfTurn: {message.transcript}")
    elif message.type == "error":
        print(f"Error: {message.message}")

# Equivalent to
# deepgram_connection.on(EventType.MESSAGE, on_message)
connection.on("event", on_message)

# Equivalent to
# threading.Thread(target=deepgram_connection.start_listening, daemon=True).start()
threading.Thread(target=connection.dispatch_events, daemon=True).start()

import Cartesia from '@cartesia/cartesia-js';

// Equivalent to
// deepgramConnection.on("message", (message) => { ... });
connection.on("event", (message: Cartesia.STT.AutoFinalize.STTAutoFinalizeWebsocketResponse) => {
  switch (message.type) {
    case "turn.start":
      console.log("StartOfTurn");
      break;
    case "turn.update":
      console.log(`Update: ${message.transcript}`);
      break;
    case "turn.eager_end":
      console.log(`EagerEndOfTurn: ${message.transcript}`);
      break;
    case "turn.resume":
      console.log("TurnResumed");
      break;
    case "turn.end":
      console.log(`EndOfTurn: ${message.transcript}`);
      break;
  }
});

// Equivalent to
// deepgramConnection.on("error", (error) => { ... });
connection.on("error", (error) => {
  if (error.error) {
    // Server sent error (may be a bad request or internal server error)
    console.error(`Server sent an error: ${error.error.message}`);
  } else {
    // Client error
    console.error(`Client had an error: ${error.message}`);
  }
});

サーバーメッセージの例

Flux のトランスクリプトはスペースで連結されます。Ink のトランスクリプトは連結されません。

Deepgram Flux	Cartesia Realtime STT (Auto)
StartOfTurn	turn.start
Update `"Flux's transcripts"`	turn.update `"Flux's transcripts"`
EagerEndOfTurn `"Flux's transcripts"`	turn.eager_end `"Flux's transcripts"`
TurnResumed	turn.resume
Update `"Flux's transcripts are joined with spaces."`	turn.update `"Flux's transcripts are joined with spaces."`
EagerEndOfTurn `"Flux's transcripts are joined with spaces."`	turn.eager_end `"Flux's transcripts are joined with spaces."`
EndOfTurn `"Flux's transcripts are joined with spaces."`	turn.end `"Flux's transcripts are joined with spaces."`
StartOfTurn	turn.start
Update `"Ink's are not."`	turn.update `" Ink's are not."`
EagerEndOfTurn `"Ink's are not."`	turn.eager_end `" Ink's are not."`
EndOfTurn `"Ink's are not."`	turn.end `" Ink's are not."`

Get Started

Text-to-Speech

Speech-to-Text

Tools

Integrations

Enterprise

Deepgram Flux からの移行

すべての移行ガイド

接続

クエリパラメーター

ターン検出

音声の送信

イベントマッピング

イベントハンドラー

サーバーメッセージの例

参照資料

API リファレンス

完全なコード例

すべての移行ガイド

​接続

​クエリパラメーター

​ターン検出

​音声の送信

​イベントマッピング

​イベントハンドラー

​サーバーメッセージの例

​参照資料

API リファレンス

完全なコード例

接続

クエリパラメーター

ターン検出

音声の送信

イベントマッピング

イベントハンドラー

サーバーメッセージの例

参照資料