Cartesia Provider

Cartesia provider는 Sonic 음성 생성, Ink-Whisper 배치 전사, 그리고 Ink 2 실시간·스트리밍 전사를 지원해요.

출처: 문서

본문

셋업 (Setup)

Cartesia provider는 @ai-sdk/cartesia 모듈에서 사용할 수 있어요. 다음과 같이 설치할 수 있어요:

pnpm add @ai-sdk/cartesia

npm install @ai-sdk/cartesia

yarn add @ai-sdk/cartesia

bun add @ai-sdk/cartesia

Provider 인스턴스 (Provider Instance)

@ai-sdk/cartesia에서 기본 provider 인스턴스인 cartesia를 import할 수 있어요:

import { cartesia } from '@ai-sdk/cartesia';

커스터마이즈된 셋업이 필요하다면 @ai-sdk/cartesia에서 createCartesia를 import하고 설정과 함께 provider 인스턴스를 만들 수 있어요:

import { createCartesia } from '@ai-sdk/cartesia';

const cartesia = createCartesia({
  // custom settings, e.g.
  fetch: customFetch,
});

Cartesia provider 인스턴스를 커스터마이즈하려면 다음 선택 설정을 사용할 수 있어요:

apiKey string — Authorization 헤더로 전송되는 API 키. 기본값은 CARTESIA_API_KEY 환경 변수예요.
version string — 사용할 Cartesia API 버전(Cartesia-Version 헤더로 전송).
headers Record<string,string> — 요청에 포함할 커스텀 헤더.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response> — 커스텀 fetch 구현. 기본값은 전역 fetch 함수. 요청을 가로채는 미들웨어로 쓰거나 테스트용 커스텀 fetch 구현을 제공하는 데 쓸 수 있어요.
webSocket WebSocketConstructor — Ink 2 스트리밍 전사용 커스텀 WebSocket 구현. 기본값은 전역 WebSocket 생성자.

음성 모델 (Speech Models)

.speech() 팩토리 메서드로 Cartesia text-to-speech API를 호출하는 모델을 만들 수 있어요.

첫 번째 인자는 모델 id, 예: sonic-3.5.

const model = cartesia.speech('sonic-3.5');

이 모델을 generateSpeech 함수와 함께 사용할 수 있어요. Cartesia는 voice id를 요구해요:

import { generateSpeech } from 'ai';
import { cartesia } from '@ai-sdk/cartesia';

const result = await generateSpeech({
  model: cartesia.speech('sonic-3.5'),
  text: 'Hello, world!',
  voice: '694f9389-aac1-45b6-b726-9d9369183238',
});

providerOptions 인자로 추가 provider별 옵션도 전달할 수 있어요:

import { generateSpeech } from 'ai';
import { cartesia, type CartesiaSpeechModelOptions } from '@ai-sdk/cartesia';

const result = await generateSpeech({
  model: cartesia.speech('sonic-3.5'),
  text: 'Hello, world!',
  voice: '694f9389-aac1-45b6-b726-9d9369183238',
  providerOptions: {
    cartesia: {
      container: 'wav',
      encoding: 'pcm_s16le',
      sampleRate: 24000,
    } satisfies CartesiaSpeechModelOptions,
  },
});

다음 provider 옵션을 사용할 수 있어요:

container string — 출력 오디오의 컨테이너 형식. 지원 값: 'raw', 'wav', 'mp3'. 선택.
encoding string — 오디오 출력의 인코딩 타입. 지원 값: 'pcm_f32le', 'pcm_s16le', 'pcm_mulaw', 'pcm_alaw'. 선택.
sampleRate number — 출력 오디오의 샘플 레이트(Hz). 예: 8000, 16000, 22050, 24000, 44100, 48000. 선택.
bitRate number — mp3 출력의 비트레이트(bps). 예: 32000, 64000, 128000, 192000. 선택.
speed number — 생성된 음성 속도 제어(0.6 ~ 1.5). 선택.
language string — 생성할 음성 언어(ISO 639-1 코드). 선택.

모델 기능 (Model Capabilities)

Model
`sonic-3.5`
`sonic-3`
`sonic-2`
`sonic-turbo`
`sonic-latest`

실시간 전사 모델 (Realtime Transcription Models)

경고: Realtime은 실험적 기능이에요.

.experimental_realtime() 팩토리 메서드로 Cartesia의 실시간 Ink 2 API용 모델을 만들 수 있어요:

import { cartesia } from '@ai-sdk/cartesia';

const model = cartesia.experimental_realtime('ink-2');

실시간 세션은 브라우저에서 실행되며, 서버에서 cartesia.experimental_realtime.getToken()으로 만든 단기 액세스 토큰이 필요해요:

const token = await cartesia.experimental_realtime.getToken({
  model: 'ink-2',
  sessionConfig: {
    inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
    inputAudioTranscription: { language: 'en' },
    turnDetection: { type: 'server-vad' },
  },
});

Ink 2는 입력 전사 이벤트를 생성하고 영어 오디오를 지원해요. 턴 감지는 기본적으로 활성화돼요. 대신 수동 확정을 사용하려면 세션 설정에서 turnDetection을 null로 설정하고 현재 입력이 끝나면 commitAudio()를 호출하세요.

전체 브라우저 세션 설정은 Realtime을 참고하세요.

모델 기능 (Model Capabilities)

Model	Streaming Transcription	Turn Detection
`ink-2`	✓	✓

스트리밍 전사 모델 (Streaming Transcription Models)

경고: 스트리밍 전사는 실험적 기능이에요.

Ink 2는 전사 스트리밍 API로도 사용할 수 있어요. .transcription()으로 모델을 만들고 experimental_streamTranscribe에 전달하세요:

import { cartesia } from '@ai-sdk/cartesia';
import { experimental_streamTranscribe as streamTranscribe } from 'ai';

const result = streamTranscribe({
  model: cartesia.transcription('ink-2'),
  audio, // ReadableStream<Uint8Array | string> containing raw audio chunks
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  providerOptions: {
    cartesia: {
      language: 'en',
    },
  },
});

for await (const part of result.fullStream) {
  if (part.type === 'transcript-partial') {
    console.log('partial:', part.text);
  }

  if (part.type === 'transcript-final') {
    console.log('final:', part.text);
  }
}

provider는 WebSocket을 열기 전에 단기, STT 범위의 Cartesia 액세스 토큰을 만들므로 API 키가 WebSocket URL에 포함되지 않아요. 오디오 청크를 대략 재생 속도로 보내세요. Cartesia의 실시간 엔드포인트는 대량 파일 업로드가 아니라 라이브 오디오용이에요.

Ink 2는 영어 오디오를 지원하고 기본적으로 Cartesia의 네이티브 턴 감지를 사용해요. 입력 오디오 스트림이 끝날 때만 확정하려면 providerOptions.cartesia.streaming.turnDetection: false를 전달하세요.

기본적으로 provider는 audio/pcm, audio/pcmu, audio/pcma를 각각 16-bit PCM, G.711 μ-law, G.711 A-law로 매핑해요. 다른 원시 PCM 표현을 스트리밍하려면 providerOptions.cartesia.streaming.encoding을 pcm_s32le, pcm_f16le, pcm_f32le로 설정하세요. 예:

const result = streamTranscribe({
  model: cartesia.transcription('ink-2'),
  audio,
  inputAudioFormat: { type: 'audio/pcm', rate: 48000 },
  providerOptions: {
    cartesia: {
      streaming: {
        encoding: 'pcm_f32le',
      },
    },
  },
});

스트리밍 전사에 대한 자세한 내용은 Transcription을 참고하세요.

모델 기능 (Model Capabilities)

Model	Streaming Transcription	Turn Detection
`ink-2`	✓	✓

배치 전사 모델 (Batch Transcription Models)

.transcription() 팩토리 메서드로 Cartesia transcription API를 호출하는 모델을 만들 수 있어요.

첫 번째 인자는 모델 id, 예: ink-whisper.

const model = cartesia.transcription('ink-whisper');

이 모델을 transcribe 함수와 함께 사용할 수 있어요:

import { transcribe } from 'ai';
import { cartesia } from '@ai-sdk/cartesia';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: cartesia.transcription('ink-whisper'),
  audio: await readFile('audio.mp3'),
});

providerOptions 인자로 추가 provider별 옵션도 전달할 수 있어요:

import { transcribe } from 'ai';
import {
  cartesia,
  type CartesiaTranscriptionModelOptions,
} from '@ai-sdk/cartesia';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: cartesia.transcription('ink-whisper'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    cartesia: {
      language: 'en',
    } satisfies CartesiaTranscriptionModelOptions,
  },
});

다음 provider 옵션을 사용할 수 있어요:

language string — 오디오 언어(ISO 639-1 코드). 지정하지 않으면 영어가 기본값. 선택.
timestampGranularities array of strings — 채울 타임스탬프 단위. 현재 'word'만 지원돼요. 선택.

모델 기능 (Model Capabilities)

Model	Transcription	Duration	Segments	Language
`ink-whisper`	✓	✓	✓	✓

Cartesia Provider