`generateSpeech()`

generateSpeech()

텍스트에서 음성 오디오(speech audio)를 생성하는 함수예요. TTS(텍스트 음성 변환) 기능을 애플리케이션에 넣고 싶을 때 가장 기본이 되는 함수랍니다. OpenAI나 ElevenLabs 같은 음성 모델과 함께 사용할 수 있어요.

출처: 문서

본문

텍스트에서 음성 오디오를 생성합니다.

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

const { audio } = await generateSpeech({
  model: openai.speech('gpt-4o-mini-tts'),
  text: 'Hello from the AI SDK!',
  voice: 'alloy',
});

console.log(audio);

예제 (Examples)

OpenAI

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

const { audio } = await generateSpeech({
  model: openai.speech('gpt-4o-mini-tts'),
  text: 'Hello from the AI SDK!',
  voice: 'alloy',
});

ElevenLabs

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

const { audio } = await generateSpeech({
  model: elevenLabs.speech('eleven_multilingual_v2'),
  text: 'Hello from the AI SDK!',
  voice: 'your-voice-id', // Required: get this from your ElevenLabs account
});

Import

import { generateSpeech } from "ai"

API 시그니처 (API Signature)

Parameters (매개변수)

<PropertiesTable content={[ { name: 'model', type: 'SpeechModelV4', description: '사용할 음성 모델.', }, { name: 'text', type: 'string', description: '음성을 생성할 텍스트.', }, { name: 'voice', type: 'string', isOptional: true, description: '음성 생성에 사용할 목소리.', }, { name: 'outputFormat', type: 'string', isOptional: true, description: '음성 생성에 사용할 출력 형식. 예: "mp3", "wav", 또는 헤더 없는 "audio/l16", "audio/mulaw", "audio/alaw". 지원되는 형식과 기본값은 프로바이더와 모델에 따라 다릅니다.', }, { name: 'instructions', type: 'string', isOptional: true, description: '음성 생성에 대한 지시 사항.', }, { name: 'speed', type: 'number', isOptional: true, description: '음성 생성 속도.', }, { name: 'language', type: 'string', isOptional: true, description: '음성 생성 언어. ISO 639-1 언어 코드(예: "en", "es", "fr") 또는 자동 언어 감지를 위한 "auto"여야 합니다. 프로바이더 지원은 다양합니다.', }, { name: 'providerOptions', type: 'Record<string, JSONObject>', isOptional: true, description: '추가적인 프로바이더별 옵션.', }, { name: 'maxRetries', type: 'number', isOptional: true, description: '최대 재시도 횟수. 기본값: 2.', }, { name: 'abortSignal', type: 'AbortSignal', isOptional: true, description: '호출을 취소할 선택적 abort signal.', }, { name: 'headers', type: 'Record<string, string>', isOptional: true, description: '요청에 대한 추가 HTTP 헤더.', }, ]} />

Returns (반환값)

<PropertiesTable content={[ { name: 'audio', type: 'GeneratedAudioFile', description: '생성된 오디오.', properties: [ { type: 'GeneratedAudioFile', parameters: [ { name: 'base64', type: 'string', description: 'base64로 인코딩된 문자열 오디오.', }, { name: 'uint8Array', type: 'Uint8Array', description: 'Uint8Array 형태의 오디오.', }, { name: 'mediaType', type: 'string', description: '오디오의 미디어 타입 (예: "audio/mpeg").', }, { name: 'format', type: 'string', description: '오디오의 형식 (예: "mp3").', }, ], }, ], }, { name: 'warnings', type: 'Warning[]', description: '모델 프로바이더의 경고(예: 지원되지 않는 설정).', }, { name: 'providerMetadata', type: 'Record<string, JSONObject>', isOptional: true, description: '프로바이더의 선택적 메타데이터. 바깥 키는 프로바이더 이름입니다. 안쪽 값은 메타데이터입니다. 세부 내용은 프로바이더에 따라 다릅니다.', }, { name: 'responses', type: 'Array', description: '프로바이더의 응답 메타데이터. 모델에 여러 번 호출했다면 여러 응답이 있을 수 있습니다.', properties: [ { type: 'SpeechModelResponseMetadata', parameters: [ { name: 'timestamp', type: 'Date', description: '생성된 응답 시작 시각.', }, { name: 'modelId', type: 'string', description: '응답을 생성하는 데 사용된 응답 모델의 ID.', }, { name: 'body', isOptional: true, type: 'unknown', description: '선택적 응답 본문.', }, { name: 'headers', type: 'Record<string, string>', isOptional: true, description: '응답 헤더.', }, ], }, ], }, ]} />

더 알아보기 (Learn more)

전체 사이트맵