음성 생성

음성 생성 (Speech)

텍스트를 사람 목소리로 읽어주는 기능, 즉 음성 합성(TTS)이 필요할 때가 있어요. AI SDK는 음성 모델로 텍스트에서 음성을 생성하는 generateSpeech 함수를 제공합니다.

출처: 공식문서

본문

가장 기본적인 사용법은 이렇습니다.

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

const audio = await generateSpeech({
  model: openai.speech('tts-1'),
  text: 'Hello, world!',
  voice: 'alloy',
});

언어 설정

음성 생성에 사용할 언어를 지정할 수도 있어요(제공자 지원 여부는 다릅니다).

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

const audio = await generateSpeech({
  model: lmnt.speech('aurora'),
  text: 'Hola, mundo!',
  language: 'es', // Spanish
});

생성된 오디오에 접근하는 방법은 이렇습니다.

const audioData = result.audio.uint8Array; // audio data as Uint8Array
// 또는
const audioBase64 = result.audio.base64; // audio data as base64 string

설정

제공자별 설정

모델별 설정은 providerOptions 파라미터로 지정할 수 있어요.

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

const audio = await generateSpeech({
  model: openai.speech('tts-1'),
  text: 'Hello, world!',
  providerOptions: {
    openai: {
      // ...
    },
  },
});

중단 신호와 타임아웃

generateSpeech는 선택적으로 AbortSignal 타입의 abortSignal 파라미터를 받아요. 음성 생성 과정을 중단하거나 타임아웃을 걸 때 씁니다.

커스텀 헤더

generateSpeech는 선택적으로 Record<string, string> 타입의 headers 파라미터를 받아 음성 생성 요청에 커스텀 헤더를 더할 수 있어요.

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

const audio = await generateSpeech({
  model: openai.speech('tts-1'),
  text: 'Hello, world!',
  headers: { 'X-Custom-Header': 'custom-value' },
});

경고(Warnings)

경고(예: 지원하지 않는 파라미터)는 warnings 속성에서 확인할 수 있어요.

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

const audio = await generateSpeech({
  model: openai.speech('tts-1'),
  text: 'Hello, world!',
});
const warnings = audio.warnings;

오류 처리

generateSpeech가 유효한 오디오를 만들지 못하면 AI_NoSpeechGeneratedError를 던져요.

이 오류는 다음 이유 중 하나로 발생할 수 있습니다.

모델이 응답을 생성하지 못했거나
모델이 생성했지만 파싱할 수 없는 응답일 때

오류는 로깅에 도움이 되도록 다음 정보를 보존합니다.

responses: 음성 모델 응답에 대한 메타데이터(타임스탬프·모델·헤더 포함)
cause: 오류의 원인. 더 상세한 오류 처리를 할 때 씁니다.

import { generateSpeech, NoSpeechGeneratedError } from 'ai';
import { openai } from '@ai-sdk/openai';

try {
  await generateSpeech({
    model: openai.speech('tts-1'),
    text: 'Hello, world!',
  });
} catch (error) {
  if (NoSpeechGeneratedError.isInstance(error)) {
    console.log('AI_NoSpeechGeneratedError');
    console.log('Cause:', error.cause);
    console.log('Responses:', error.responses);
  }
}

음성 모델

OpenAI(tts-1, tts-1-hd, gpt-4o-mini-tts), Mistral(voxtral-mini-tts-2603), ElevenLabs(eleven_v3 외 다수), LMNT(aurora, blizzard), Hume(default), Google/Google Vertex, xAI(default), Cartesia(sonic-3.5 외), Fish Audio(s1 외) 등 다양한 제공자에서 음성 모델을 지원해요. 위 목록은 AI SDK 제공자들이 지원하는 음성 모델 중 일부에 불과하니, 더 자세한 내용은 각 제공자 문서를 참고하세요.

더 알아보기

구조화된 데이터 생성의 Output 활용과 유사한 파라미터 구성
음성 전사(Transcription)로 오디오를 텍스트로
음성 모델 API 레퍼런스(generateSpeech)