AssemblyAI 프로바이더

AssemblyAI 프로바이더

AssemblyAI의 음성 인식(transcription) API를 AI SDK에서 쓸 수 있게 해주는 프로바이더예요. 강력한 전사 모델과 풍부한 오디오 인텔리전스 기능을 지원해요.

출처: 문서

본문

AssemblyAI 프로바이더는 AssemblyAI 전사 API에 대한 음성 인식 모델 지원을 제공해요.

설정 (Setup)

AssemblyAI 프로바이더는 @ai-sdk/assemblyai 모듈에서 사용할 수 있어요. 다음과 같이 설치할 수 있어요:

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

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

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

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

import { createAssemblyAI } from '@ai-sdk/assemblyai';

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

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

  • apiKey string

    Authorization 헤더로 보내는 API 키예요. 기본값은 ASSEMBLYAI_API_KEY 환경 변수예요.

  • headers Record<string,string>

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

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

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

음성 인식 모델 (Transcription Models)

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

첫 번째 인자는 모델 id예요. 예: universal-3-5-pro.

const model = assemblyai.transcription('universal-3-5-pro');

best 모델은 사용 중단된 레거시 모델로, AssemblyAI의 사용 중단된 speech_model 요청 파라미터로 전송돼요. 여전히 동작하지만 사용하면 사용 중단 경고가 발생해요 — universal-3-5-pro를 선호하세요. 이전의 nano 모델은 AssemblyAI에 의해 제거되어 더 이상 사용할 수 없어요. 모든 최신 모델은 프로바이더가 모델 id에 따라 자동으로 선택하는 speech_models 요청 파라미터로 전송돼요.

universal-3-pro와 universal-2는 완전히 지원되며 계속 동작하지만, 사용하면 AssemblyAI의 최신 플래그십 모델인 universal-3-5-pro를 제안하는 정보성 경고(사용 중단이 아님)를 발생시켜요.

providerOptions 인자로 프로바이더별 추가 옵션을 전달할 수도 있어요. 예를 들어 contentSafety 옵션을 제공하면 콘텐츠 안전 필터링이 활성화돼요.

import { transcribe } from 'ai';
import { assemblyai } from '@ai-sdk/assemblyai';
import { type AssemblyAITranscriptionModelOptions } from '@ai-sdk/assemblyai';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: assemblyai.transcription('universal-3-5-pro'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    assemblyai: {
      contentSafety: true,
    } satisfies AssemblyAITranscriptionModelOptions,
  },
});

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

  • audioEndAt number

    오디오의 종료 시간(밀리초)이에요. 선택.

  • audioStartFrom number

    오디오의 시작 시간(밀리초)이에요. 선택.

  • autoChapters boolean

    전사에 대해 챕터를 자동 생성할지 여부예요. 선택.

  • autoHighlights boolean

    전사에 대해 하이라이트를 자동 생성할지 여부예요. 선택.

  • boostParam enum

    wordBoost의 부스트 파라미터예요. 허용 값: 'low', 'default', 'high'. 사용 중단 — 사용 중단된 wordBoost에만 적용됨; 대신 keytermsPrompt를 사용하세요. 선택.

  • contentSafety boolean

    콘텐츠 안전 필터링을 활성화할지 여부예요. 선택.

  • contentSafetyConfidence number

    콘텐츠 안전 필터링의 신뢰도 임계값 (25-100). 선택.

  • customSpelling array of objects

    전사의 커스텀 철자 규칙이에요. 각 객체는 from(문자열 배열)과 to(문자열) 속성을 가져요. 선택.

  • disfluencies boolean

    전사에 불유창성(disfluencies, um, uh 등)을 포함할지 여부예요. 선택.

  • domain string

    전문 용어를 위한 도메인별 모델을 활성화해요. 현재 'medical-v1'(Medical Mode)을 지원해요. 선택.

  • entityDetection boolean

    전사에서 개체(엔티티)를 감지할지 여부예요. 선택.

  • filterProfanity boolean

    전사에서 욕설을 필터링할지 여부예요. 선택.

  • formatText boolean

    전사에서 텍스트를 포맷할지 여부예요. 선택.

  • iabCategories boolean

    전사에 IAB 카테고리를 포함할지 여부예요. 선택.

  • keytermsPrompt array of strings

    인식도를 높이기 위한 도메인별 핵심 용어 (구당 최대 6단어). 최신 모델에서는 wordBoost를 대체 — universal-3-pro, universal-3-5-pro, slam-1 (및 활성화된 universal-2)에서 지원. 선택.

  • languageCode string

    오디오의 언어 코드예요. 많은 ISO-639-1 및 ISO-639-3 언어 코드를 지원해요. 선택.

  • languageConfidenceThreshold number

    언어 감지의 신뢰도 임계값이에요. 선택.

  • languageDetection boolean

    언어 감지를 활성화할지 여부예요. 선택.

  • languageDetectionOptions object

    자동 언어 감지 옵션: expectedLanguages(문자열 배열), fallbackLanguage(문자열), codeSwitching(boolean), codeSwitchingConfidenceThreshold(number, 0-1). 선택.

  • multichannel boolean

    여러 오디오 채널을 별도로 처리할지 여부예요. 선택.

  • prompt string

    모델을 안내하는 자연어 컨텍스트 (최대 1,500단어). universal-3-pro, universal-3-5-pro, slam-1에서만 지원. 선택.

  • punctuate boolean

    전사에 구두점을 추가할지 여부예요. 선택.

  • redactPii boolean

    개인 식별 정보(PII)를 마스킹할지 여부예요. 선택.

  • redactPiiAudio boolean

    오디오 파일에서 PII를 마스킹할지 여부예요. 선택.

  • redactPiiAudioOptions object

    PII 마스킹된 오디오 옵션: returnRedactedNoSpeechAudio(boolean), overrideAudioRedactionMethod('silence'). redactPiiAudio가 필요해요. 선택.

  • redactPiiAudioQuality enum

    마스킹된 오디오 파일의 품질이에요. 허용 값: 'mp3', 'wav'. 선택.

  • redactPiiPolicies array of enums

    PII 마스킹 정책으로, 마스킹할 정보 유형을 지정해요. 'person_name', 'phone_number' 등 여러 유형을 지원해요. 선택.

  • redactPiiReturnUnredacted boolean

    마스킹된 것과 함께 원본 마스킹 안 된 트랜스크립트를 반환할지 여부예요. redactPii가 필요해요. 선택.

  • redactPiiSub enum

    마스킹된 PII의 대체 방법이에요. 허용 값: 'entity_name', 'hash'. 선택.

  • redactStaticEntities object

    사용자 정의 레이블을 정확한 마스킹 용어에 매핑한 맵이에요. 예: { INTERNAL_TOOL: ['Bearclaw'] }. 표준 PII 마스킹 위에 적용돼요. redactPii가 필요해요. 선택.

  • removeAudioTags enum

    풍부한 트랜스크립트에서 인라인 주석을 제거해요. 허용 값: 'all'(모든 주석), 'speaker'(화자 단서만). Universal-3 Pro 모델. 선택.

  • sentimentAnalysis boolean

    전사에 감정 분석을 수행할지 여부예요. 선택.

  • speakerLabels boolean

    전사에서 다른 화자를 라벨링할지 여부예요. 선택.

  • speakerOptions object

    화자 분리(diarization) 옵션: minSpeakersExpected(number), maxSpeakersExpected(number). 선택.

  • speakersExpected number

    오디오의 예상 화자 수예요. 선택.

  • speechThreshold number

    음성 감지 임계값 (0-1). 선택.

  • summarization boolean

    전사 요약을 생성할지 여부예요. 선택.

  • summaryModel enum

    요약에 사용할 모델이에요. 허용 값: 'informative', 'conversational', 'catchy'. 선택.

  • summaryType enum

    생성할 요약 유형이에요. 허용 값: 'bullets', 'bullets_verbose', 'gist', 'headline', 'paragraph'. 선택.

  • temperature number

    무작위성을 제어하는 샘플링 온도 (0-1). Universal-3 Pro 모델. 선택.

  • webhookAuthHeaderName string

    웹훅 요청의 인증 헤더 이름이에요. 선택.

  • webhookAuthHeaderValue string

    웹훅 요청의 인증 헤더 값이에요. 선택.

  • webhookUrl string

    웹훅 알림을 보낼 URL이에요. 선택.

  • wordBoost array of strings

    전사에서 높일 단어 목록이에요. 사용 중단 — universal-3-pro, universal-3-5-pro, slam-1에서 거부됨 (universal-2/best에서만 동작); 대신 keytermsPrompt를 사용하세요. 선택.

화자 분리 및 오디오 인텔리전스 결과 (Speaker diarization and audio-intelligence results)

AI SDK의 transcribe 결과는 text, segments, language, durationInSeconds를 노출해요. AssemblyAI의 더 풍부한 결과 — 화자 분리와 오디오 인텔리전스 기능 — 는 그 형식에 맞지 않아 두 곳에 표시돼요:

  • providerMetadata.assemblyai — 활성화한 기능의 구조화된 결과: utterances(speakerLabels가 설정된 경우 화자 분리 세그먼트), entities, sentimentAnalysisResults, contentSafetyLabels, iabCategoriesResult, autoHighlightsResult.
  • response.body — 완전하고 원시적인 AssemblyAI 트랜스크립트 응답이므로, 위에 표시되지 않은 필드(예: chapters, 단어 수준 speaker 라벨)도 여전히 사용할 수 있어요.

참고: providerMetadata와 response.body 내부의 타이밍(예: utterances[].start)은 AssemblyAI API와 일치하는 밀리초 단위예요 — 반면 최상위 segments는 초를 사용해요.

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

const result = await transcribe({
  model: assemblyai.transcription('universal-3-5-pro'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    assemblyai: {
      speakerLabels: true,
      entityDetection: true,
    },
  },
});

const { utterances, entities } = result.providerMetadata?.assemblyai ?? {};
// utterances: [{ speaker: 'A', text: '…', start, end, … }, …]  (start/end in ms)

다음 AssemblyAI 기능은 API에 의해 사용 중단되었으며 providerMetadata에 표시되지 않아요 (활성화하면 출력이 원시 response.body에 남아 있음): 요약, 자동 챕터, 커스텀 토픽. 또한 일부 기능은 언어 제한이 있어요(예: 감정 분석은 영어 중심). 언어별 가용성은 AssemblyAI 문서를 참고하세요.

모델 기능 (Model Capabilities)

모델 음성 인식 지속 시간 세그먼트 언어
universal-3-5-pro
universal-3-pro
universal-2
best

더 알아보기 (Learn more)

전체 사이트맵