Fish Audio Provider

Fish Audio provider는 음성 생성(S1 및 S2 모델)과 음성-대-텍스트 전사 지원을 담아요.

출처: 문서

본문

셋업 (Setup)

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

pnpm add @ai-sdk/fish-audio

npm install @ai-sdk/fish-audio

yarn add @ai-sdk/fish-audio

bun add @ai-sdk/fish-audio

Provider 인스턴스 (Provider Instance)

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

import { fishAudio } from '@ai-sdk/fish-audio';

커스터마이즈된 셋업이 필요하면 @ai-sdk/fish-audio에서 createFishAudio를 import하고 설정으로 provider 인스턴스를 만들 수 있어요:

import { createFishAudio } from '@ai-sdk/fish-audio';

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

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

apiKey string — Authorization 헤더로 전송되는 API 키. 기본값은 FISH_AUDIO_API_KEY 환경 변수.
baseURL string — API 호출의 기본 URL. 기본값 https://api.fish.audio.
headers Record<string,string> — 요청에 포함할 커스텀 헤더.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response> — 커스텀 fetch 구현. 기본값은 전역 fetch 함수. 요청을 가로채는 미들웨어로 쓰거나 테스트용 커스텀 fetch 구현을 제공하는 데 쓸 수 있어요.

음성 모델 (Speech Models)

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

import { fishAudio } from '@ai-sdk/fish-audio';
import { generateSpeech } from 'ai';

const { audio } = await generateSpeech({
  model: fishAudio.speech('s1'),
  text: 'Hello from Fish Audio!',
});

voice 옵션은 Fish Audio 음성 라이브러리 또는 직접 업로드한 모델에서 Fish Audio 음성 모델 ID(reference_id)를 선택해요. 생략하면 기본 음성이 사용돼요.

const { audio } = await generateSpeech({
  model: fishAudio.speech('s1'),
  text: 'Hello from Fish Audio!',
  voice: '933563129e564b19a115bedd57b7406a',
  outputFormat: 'opus',
  speed: 1.1,
});

음성 목록은 AI SDK 음성 모델 명세의 일부가 아니므로, Fish Audio list-models 엔드포인트로 직접 음성을 찾아보세요:

const response = await fetch(
  'https://api.fish.audio/model?page_size=20&sort_by=task_count',
  { headers: { Authorization: *** ${process.env.FISH_AUDIO_API_KEY}` } },
);
const { items } = await response.json();
// Each item's `_id` is a value you can pass as `voice`.

자신이 업로드한 모델만 나열하려면 self=true를, 필터링하려면 language=en / tag=narration을 추가하세요.

Provider 옵션 (Provider Options)

다음 provider 옵션이 있어요:

referenceId string | array of strings — 음성 모델 ID. 단일 ID는 화자 하나를 선택하고, 배열은 다중 화자 대화를 활성화해요(S2-Pro 모델). 최상위 voice 옵션보다 우선해요. 선택.
sampleRate number — 출력 샘플 레이트(Hz). 설정하지 않으면 형식 기본값으로 폴백(wav/pcm/mp3는 44100 Hz, opus는 48000 Hz). 선택.
mp3Bitrate 64 | 128 | 192 — mp3 출력의 비트레이트(kbps). 다른 형식에선 무시돼요. 선택.
opusBitrate -1000 | 24000 | 32000 | 48000 | 64000 — opus 출력의 비트레이트(bps), -1000은 자동 선택. 다른 형식에선 무시돼요. 선택.
latency 'low' | 'normal' | 'balanced' — 지연/품질 트레이드오프. normal이 최고 품질, balanced는 지연 감소, low가 가장 빠름. 선택.
volume number — 볼륨 오프셋(dB). 음수 값은 더 조용함. 선택.
normalizeLoudness boolean — 음량 정규화. S2 제품군(s2-pro, s2.1-pro)에서 지원. Fish Audio가 s1에서도 받지만 무시하므로, provider는 그 경우 이를 버리고 경고를 emit해요. 선택.
temperature number — 표현력 제어(0~1). 높을수록 더 다양함. 선택.
topP number — nucleus 샘플링으로 다양성 제어(0~1). 선택.
chunkLength number — 처리용 텍스트 세그먼트 크기(100~300). 선택.
minChunkLength number — 새 청크로 분할하기 전 최소 문자 수(0~100). 선택.
normalize boolean — 영어와 중국어 텍스트 정규화. 숫자 안정성에 도움. 선택.
maxNewTokens number — 텍스트 청크당 생성할 최대 오디오 토큰. 선택.
repetitionPenalty number — 1.0보다 높은 값은 반복 오디오 패턴을 억제. 선택.
conditionOnPreviousChunks boolean — 청크 간 음성 일관성을 위해 이전 오디오를 컨텍스트로 재사용. 선택.
earlyStopThreshold number — 배치 처리에 사용되는 조기 중지 임계값(0~1). 선택.
features array of strings — 추론 백엔드에 전달되는 요청 범위 플래그, 예: ['quality-guard']. 선택.

다중 화자 대화 (Multi-Speaker Dialogue)

S2-Pro 모델은 다중 화자 대화를 지원해요. referenceId로 음성 모델 ID 배열을 전달하고 텍스트에서 <|speaker:N|>로 턴을 표시하세요. 여기서 N은 그 배열을 인덱싱해요.

const { audio } = await generateSpeech({
  model: fishAudio.speech('s2-pro'),
  text: '<|speaker:0|>Hello!<|speaker:1|>Hi there!',
  providerOptions: {
    fishAudio: {
      referenceId: [
        '933563129e564b19a115bedd57b7406a',
        'bf322df2096a46f18c579d0baa36f41d',
      ],
    },
  },
});

출력 형식 (Output Formats)

Fish Audio는 wav, pcm, mp3, opus 출력 형식을 지원해요. 다른 값은 mp3로 폴백하고 경고를 생성해요.

참고: Fish Audio는 입력 텍스트와 선택된 음성에서 언어를 추론하며 언어 파라미터가 없어요. language와 instructions 옵션은 지원되지 않고 경고를 생성해요.

모델 기능 (Model Capabilities)

Model	Multi-Speaker	Notes
`s1`		`normalizeLoudness` 무시
`s2-pro`	✓	`normalizeLoudness` 지원
`s2.1-pro`	✓	권장 기본값; `normalizeLoudness` 지원
`s2.1-pro-free`		무료 개발자 티어; 첫 오디오 시간·데이터 처리 보장 없음

참고: 스트리밍 text-to-speech(Fish Audio의 TTS-live WebSocket과 타임스탬프 스트리밍 엔드포인트)는 현재 지원되지 않아요. references를 통한 인라인 제로샷 음성 복제도 지원되지 않는데, 이는 MessagePack 요청 본문이 필요해요. 대신 참조 오디오를 Fish Audio에 업로드하고 voice나 referenceId로 그 reference_id를 전달하세요.

전사 모델 (Transcription Models)

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

import { fishAudio } from '@ai-sdk/fish-audio';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: fishAudio.transcription(),
  audio: await readFile('audio.mp3'),
});

Fish Audio speech-to-text 엔드포인트는 현재 모델 선택기를 노출하지 않고 단일 모델을 제공하므로 모델 ID는 선택 사항이며 기본값은 'transcribe-1'이에요. 이는 라우팅 라벨이며 API로 전송되지 않아요. Fish Audio는 더 많은 ASR 모델을 추가하고 text-to-speech 엔드포인트처럼 model HTTP 헤더로 선택할 예정이에요.

Provider 옵션 (Provider Options)

다음 provider 옵션이 있어요:

language string — 오디오 언어. 힌트일 뿐: Fish Audio가 모델에 전달하지만 자동 감지가 우선해 이를 재정의하므로, 트랜스크립트나 보고된 언어를 바꾸지 않아요. 선택.
ignoreTimestamps boolean — 정밀 타임스탬프를 건너뛸지. Fish Audio의 ignore_timestamps 파라미터를 반영하며 API 기본값은 true. 이 provider는 segments가 채워지도록 기본값을 false로 설정해요. Fish Audio는 30초보다 짧은 오디오에 추가 지연 비용을 문서화했으므로, 이 지연과 세그먼트를 맞바꾸려면 true로 설정하세요. 선택.

const result = await transcribe({
  model: fishAudio.transcription(),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    fishAudio: {
      language: 'en',
      ignoreTimestamps: false,
    },
  },
});

result.language는 감지된 언어를 ISO-639-1 코드로 보고해요(예: en). 항상 두 글자 코드이며 en-US 같은 로케일이 절대 아니고, Fish Audio가 언어를 감지하지 못하면 undefined예요.

사람이 읽는 언어 이름(예: English)은 provider 메타데이터로 사용할 수 있어요:

console.log(result.language); // 'en'
console.log(result.providerMetadata?.fishAudio?.language); // 'English'

참고: provider 메타데이터 language는 표시용 이름이에요. 정확한 형식이 보장되지 않으므로 일치·분기하지 말고, 프로그램적인 것은 result.language를 사용하세요.

참고: ignoreTimestamps를 true로 설정하면 Fish Audio가 빈 segments 배열을 반환해요. 따라서 provider는 기본적으로 타임스탬프를 요청해요.

모델 기능 (Model Capabilities)

Model	Transcription	Duration	Segments	Language
`transcribe-1`	✓	✓	✓	✓

Fish Audio Provider