ElevenLabs 프로바이더

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/elevenlabs에서 기본 프로바이더 인스턴스 elevenLabs를 불러올 수 있어요:

import { elevenLabs } from '@ai-sdk/elevenlabs';

커스터마이즈가 필요하다면 @ai-sdk/elevenlabs에서 createElevenLabs를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createElevenLabs } from '@ai-sdk/elevenlabs';

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

ElevenLabs 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• apiKey string

  xi-api-key 헤더로 보내는 API 키예요. 기본값은 ELEVENLABS_API_KEY 환경 변수예요.

• headers Record<string,string>

  요청에 포함할 커스텀 헤더예요.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

• webSocket WebSocketConstructor

  실시간 음성 인식을 위한 커스텀 WebSocket 구현이에요. 네이티브 WebSocket 생성자가 xi-api-key 인증 헤더를 보낼 수 없는 런타임에서는 헤더를 지원하는 구현이 필요해요.

음성 모델 (Speech Models)

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

첫 번째 인자는 모델 id예요. 예를 들면 eleven_multilingual_v2죠.

const model = elevenLabs.speech('eleven_multilingual_v2');

voice 인자에는 ElevenLabs Voice Library의 음성 ID를 설정할 수 있어요. 라이브러리에서 음성을 선택하고 ID를 복사하면 음성 ID를 찾을 수 있어요.

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

const result = await generateSpeech({
  model: elevenLabs.speech('eleven_multilingual_v2'),
  text: 'Hello, world!',
  voice: '21m00Tcm4TlvDq8ikWAM', // Rachel voice
});

providerOptions 인자로 프로바이더별 추가 옵션을 전달할 수도 있어요:

import { generateSpeech } from 'ai';
import {
  elevenLabs,
  type ElevenLabsSpeechModelOptions,
} from '@ai-sdk/elevenlabs';

const result = await generateSpeech({
  model: elevenLabs.speech('eleven_multilingual_v2'),
  text: 'Hello, world!',
  voice: '21m00Tcm4TlvDq8ikWAM',
  providerOptions: {
    elevenlabs: {
      voiceSettings: {
        stability: 0.5,
        similarityBoost: 0.75,
      },
    } satisfies ElevenLabsSpeechModelOptions,
  },
});

• languageCode string or null
  선택 사항이에요. 모델에 특정 언어를 강제하기 위한 언어 코드(ISO 639-1)예요. 현재 Turbo v2.5와 Flash v2.5만 언어 강제를 지원해요. 다른 모델에 언어 코드를 제공하면 오류가 발생해요.

• voiceSettings object or null
  선택 사항이에요. 주어진 음성에 저장된 설정을 덮어쓰는 음성 설정이에요. 현재 요청에만 적용돼요.

  • stability double or null
    선택 사항이에요. 음성이 얼마나 안정적인지, 그리고 생성 사이의 무작위성을 결정해요. 값이 낮을수록 감정의 폭이 넓어지고, 높을수록 더 단조로운 목소리가 돼요.
  • useSpeakerBoost boolean or null
    선택 사항이에요. 원래 화자와의 유사도를 높여줘요. 연산 부하와 지연 시간이 늘어나요.
  • similarityBoost double or null
    선택 사항이에요. AI가 원래 목소리를 얼마나 밀접하게 따라야 하는지 조절해요.
  • style double or null
    선택 사항이에요. 원래 화자의 스타일을 강조해요. 0보다 크게 설정하면 지연 시간이 늘어날 수 있어요.

• pronunciationDictionaryLocators array of objects or null
  선택 사항이에요. 텍스트에 적용할 발음 사전 locator 목록이에요. 요청당 최대 3개까지 지정할 수 있어요.
  각 locator 객체:

  • pronunciationDictionaryId string (필수)
    발음 사전의 ID예요.
  • versionId string or null (선택)
    사전의 버전 ID예요. 제공하지 않으면 최신 버전이 사용돼요.

• seed integer or null
  선택 사항이에요. 지정하면 시스템이 결정적으로 샘플링을 시도해요. 0~4294967295 사이여야 해요. 결정성은 보장되지 않아요.

• previousText string or null
  선택 사항이에요. 현재 요청의 텍스트 앞에 있던 텍스트예요. 생성 결과를 이어 붙일 때 연속성을 높이거나 현재 생성의 연속성에 영향을 줄 수 있어요.

• nextText string or null
  선택 사항이에요. 현재 요청의 텍스트 뒤에 오는 텍스트예요. 생성 결과를 이어 붙일 때 연속성을 높이거나 현재 생성의 연속성에 영향을 줄 수 있어요.

• previousRequestIds array of strings or null
  선택 사항이에요. 이전에 생성된 샘플의 요청 ID 목록이에요. 큰 작업을 나눌 때 연속성을 높여줘요. 최대 3개 ID까지 가능해요. previousText와 previousRequestIds가 모두 전달되면 previousText는 무시돼요.

• nextRequestIds array of strings or null
  선택 사항이에요. 이후에 생성된 샘플의 요청 ID 목록이에요. 샘플을 재생성할 때 연속성을 유지하는 데 유용해요. 최대 3개 ID까지 가능해요. nextText와 nextRequestIds가 모두 전달되면 nextText는 무시돼요.

• applyTextNormalization enum
  선택 사항이에요. 텍스트 정규화를 조절해요.
  허용 값: 'auto'(기본), 'on', 'off'.

  • 'auto': 시스템이 정규화 적용 여부(예: 숫자 철자 풀기)를 결정해요.
  • 'on': 항상 정규화를 적용해요.
  • 'off': 절대 정규화를 적용하지 않아요.
    eleven_turbo_v2_5와 eleven_flash_v2_5의 경우 Enterprise 플랜에서만 활성화할 수 있어요.

• applyLanguageTextNormalization boolean
  선택 사항이에요. 기본값은 false예요. 일부 지원 언어(현재는 일본어만)에서 올바른 발음에 도움이 되는 언어 텍스트 정규화를 조절해요. 지연 시간이 크게 늘어날 수 있어요.

• enableLogging boolean
  선택 사항이에요. 이 API 호출에 대해 요청 로깅을 활성화할지 여부예요. 기본값은 계정 수준 설정이에요.

모델 기능 (Model Capabilities)

음성 인식 모델 (Transcription Models)

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

첫 번째 인자는 모델 id예요. 예를 들면 scribe_v2죠.

const model = elevenLabs.transcription('scribe_v2');

providerOptions 인자로 프로바이더별 추가 옵션을 전달할 수도 있어요. 예를 들어 입력 언어를 ISO-639-1(예: en) 형식으로 미리 알려주면 음성 인식 성능이 향상될 때가 있어요.

import { transcribe } from 'ai';
import {
  elevenLabs,
  type ElevenLabsTranscriptionModelOptions,
} from '@ai-sdk/elevenlabs';

const result = await transcribe({
  model: elevenLabs.transcription('scribe_v2'),
  audio: new Uint8Array([1, 2, 3, 4]),
  providerOptions: {
    elevenlabs: {
      languageCode: 'en',
    } satisfies ElevenLabsTranscriptionModelOptions,
  },
});

다음 프로바이더 옵션들을 사용할 수 있어요:

• languageCode string

  오디오 파일의 언어에 해당하는 ISO-639-1 또는 ISO-639-3 언어 코드예요. 미리 알고 있으면 음성 인식 성능을 향상시킬 수 있어요. 기본값은 null이며, 이 경우 언어가 자동으로 예측돼요.

• tagAudioEvents boolean

  (웃음), (발소리) 같은 오디오 이벤트를 음성 인식 결과에 태그할지 여부예요. 기본값은 true예요.

• numSpeakers integer

  업로드된 파일에서 말하는 화자의 최대 수예요. 누가 언제 말하는지 예측하는 데 도움이 돼요. 예측할 수 있는 화자의 최대 수는 32예요. 기본값은 null이며, 이 경우 화자 수는 모델이 지원하는 최대값으로 설정돼요.

• timestampsGranularity enum

  음성 인식 결과에서 타임스탬프의 세밀도예요. 기본값은 'word'예요. 허용 값: 'none', 'word', 'character'.

• diarize boolean

  업로드된 파일에서 현재 누가 말하는지 주석을 달지 여부예요. 기본값은 true예요.

• fileFormat enum

  입력 오디오의 형식이에요. 기본값은 'other'예요. 허용 값: 'pcm_s16le_16', 'other'. 'pcm_s16le_16'의 경우 입력 오디오는 16kHz 샘플레이트, 단일 채널(모노), 리틀엔디언 바이트 순서의 16비트 PCM이어야 해요. 인코딩된 파형을 전달하는 것보다 지연 시간이 더 낮아요.

모델 기능 (Model Capabilities)

스트리밍 음성 인식 모델 (Streaming Transcription Models)

스트리밍 음성 인식은 실험적인 기능이에요.

Scribe v2 Realtime은 experimental_streamTranscribe를 통한 실시간 음성 인식을 지원해요. 8, 16, 22.05, 24, 44.1 또는 48 kHz의 원시 PCM 오디오나 8 kHz mu-law 오디오를 받아요.

import {
  createElevenLabs,
  type ElevenLabsProviderSettings,
} from '@ai-sdk/elevenlabs';
import { experimental_streamTranscribe as streamTranscribe } from 'ai';
import { WebSocket } from 'ws';

const elevenLabs = createElevenLabs({
  webSocket: WebSocket as unknown as ElevenLabsProviderSettings['webSocket'],
});

const result = streamTranscribe({
  model: elevenLabs.transcription('scribe_v2_realtime'),
  audio,
  inputAudioFormat: { type: 'audio/pcm', rate: 16000 },
  providerOptions: {
    elevenlabs: {
      languageCode: 'en',
      streaming: {
        includeLanguageDetection: true,
        includeTimestamps: true,
      },
    },
  },
});

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);
  }
}

ElevenLabs 실시간 엔드포인트는 WebSocket 헤더로 인증해요. 네이티브 WebSocket 생성자가 헤더를 보낼 수 없는 런타임에서는 ws 같은 헤더 지원 WebSocket 구현을 사용하세요.

streaming 프로바이더 옵션은 ElevenLabs의 실시간 음성 인식 설정을 그대로 반영해요: commitStrategy, enableLogging, filterBackgroundAudio, includeLanguageDetection, includeTimestamps, keyterms, minSilenceDurationMs, minSpeechDurationMs, noVerbatim, previousText, secondaryLanguages, vadSilenceThresholdSecs, vadThreshold.

ElevenLabs는 타임스탬프를 포함하는 커밋된 이벤트에서 감지된 언어를 전달해요. includeLanguageDetection을 활성화하면 프로바이더가 내부적으로 해당 이벤트를 요청하지만, includeTimestamps도 활성화된 경우에만 타임스탬프 세그먼트를 반환해요. filterBackgroundAudio는 두 옵션 중 어느 것과도 함께 쓸 수 없어요.

스트리밍 음성 인식에 대한 자세한 내용은 Transcription을 참고하세요.

모델 기능 (Model Capabilities)

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵