fal.ai

fal.ai 어댑터는 이미지, 동영상, 오디오, 음성 및 전사를 위한 fal.ai 플랫폼의 600개 이상의 모델에 액세스할 수 있게 합니다. 텍스트 중심 어댑터와 달리 fal 어댑터는 미디어 중심이며 generateImage(), generateVideo(), generateAudio(), generateSpeech(), generateTranscription()을 지원하지만 chat() 또는 도구는 지원하지 않습니다.

완전히 작동하는 예제는 fal.ai 예제 앱을 참고하세요.

설치

npm install @tanstack/ai-fal

문자열 리터럴을 사용한 타입 안전성

모델 ID를 문자열 리터럴로 전달하면 fal 어댑터가 완전한 타입 안전성을 제공합니다. 해당 모델에 특화된 size 및 modelOptions의 자동 완성도 사용할 수 있습니다. 어댑터를 만들 때는 항상 변수 대신 문자열 리터럴을 사용하세요.

import { falImage } from "@tanstack/ai-fal";

// Good — full type safety and autocomplete
const adapter = falImage("fal-ai/z-image/turbo");

import { falImage } from "@tanstack/ai-fal";

// Bad — no type inference for model-specific options
const modelId = "fal-ai/z-image/turbo";
const adapter = falImage(modelId);

fal.ai가 아직 타입을 제공하지 않는 새로운 모델에는 어떤 문자열이든 전달할 수 있지만, 해당 엔드포인트에서는 타입 안전성을 사용할 수 없습니다.

기본 사용법

import { generateImage } from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

const result = await generateImage({
  adapter: falImage("fal-ai/flux/dev"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
});

console.log(result.images);

기본 사용법 - 사용자 지정 API 키

import { generateImage } from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

const adapter = falImage("fal-ai/flux/dev", {
  apiKey: process.env.FAL_KEY!,
});

const result = await generateImage({
  adapter,
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
});

구성

import { falImage, type FalClientConfig } from "@tanstack/ai-fal";

// Direct API key
const adapter = falImage("fal-ai/flux/dev", {
  apiKey: "your-api-key",
});

// Using a proxy URL (for client-side usage)
const proxiedAdapter = falImage("fal-ai/flux/dev", {
  apiKey: "your-api-key",
  proxyUrl: "https://your-server.com/api/fal/proxy",
});

예제: 이미지 생성

다음은 fal.ai 예제 앱의 예제입니다.

import { generateImage } from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

// Use string literals for the model to get full type safety
const result = await generateImage({
  adapter: falImage("fal-ai/nano-banana-pro"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
  size: "16:9_4K",
  modelOptions: {
    output_format: "jpeg",
  },
});

예제: 모델 옵션을 사용한 이미지

각 fal.ai 모델에는 고유한 타입 안전 옵션이 있습니다. 어댑터는 fal.ai의 타입을 사용해 모델별 매개변수에 대한 자동 완성 및 타입 검사를 제공합니다. 조합은 수천 가지입니다. 올바른 모델 엔드포인트 ID를 문자열 리터럴로 제공하면 해당 모델이 지원하는 size 및 modelOptions만 제공할 수 있습니다.

중요: Fal이 아직 타입을 제공하지 않는 문자열과 새로운 엔드포인트 ID도 전달할 수 있습니다. 다만 해당 엔드포인트에서는 타입 안전성을 사용할 수 없습니다. 매우 새로운 모델에서 이런 경우가 발생합니다.

import { generateImage } from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

// Model-specific options are type-safe
const result = await generateImage({
  adapter: falImage("fal-ai/z-image/turbo"),
  prompt: "A serene mountain landscape",
  numberOfImages: 1,
  size: "landscape_16_9",
  modelOptions: {
    acceleration: "high",
    enable_prompt_expansion: true,
  },
});

이미지 크기 옵션

fal 어댑터는 image_size 또는 aspect_ratio와 resolution 매개변수에 매핑되는 유연한 size 매개변수를 지원합니다.

	`size`	매핑 대상
named	`"landscape_16_9"`	`image_size: "landscape_16_9"`
너비 x 높이 (OpenAI)	`"1536x1024"`
纵横비 및 해상도	`"16:9_4K"`	`aspect_ratio: "16:9"`, `resolution: "4K"`
纵横비만	`"16:9"`	`aspect_ratio: "16:9"`

// Aspect ratio only
size: "16:9"

// Aspect ratio with resolution
size: "16:9_4K"

// Named size (model-specific)
size: "landscape_16_9"

동영상 생성(실험적)

참고: 동영상 생성은 실험적 기능이며 향후 릴리스에서 변경될 수 있습니다.

동영상 생성은 큐 기반 워크플로를 사용합니다. 작업을 제출하고 상태를 폴링한 다음, 완료되면 동영상 URL을 가져옵니다.

import { generateVideo, getVideoJobStatus } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

예제: 텍스트에서 동영상으로

다음은 fal.ai 예제 앱의 예제입니다.

import { generateVideo, getVideoJobStatus } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

// 1. Submit the video generation job
const adapter = falVideo("fal-ai/kling-video/v2.6/pro/text-to-video");

const job = await generateVideo({
  adapter,
  prompt: "A timelapse of a flower blooming",
  size: "16:9",
  duration: "5",
});

// 2. Poll for status
const status = await getVideoJobStatus({
  adapter,
  jobId: job.jobId,
});

console.log(status.status); // "pending" | "processing" | "completed"

예제: 이미지에서 동영상으로

import { generateVideo } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

const job = await generateVideo({
  adapter: falVideo("fal-ai/kling-video/v2.6/pro/image-to-video"),
  prompt: "Animate this scene with gentle wind",
  duration: "5",
  modelOptions: {
    start_image_url: "https://example.com/image.jpg",
    generate_audio: true,
  },
});

duration은 @fal-ai/client의 EndpointTypeMap에 따라 모델별로 타입이 지정됩니다. 인기 모델은 UI 슬라이더를 위한 availableDurations() / snapDuration()도 구현합니다.

모델	`duration` type	`availableDurations()`
`fal-ai/kling-video/v1.6/{standard,pro}/text-to-video`, `fal-ai/kling-video/v2.6/pro/{text,image}-to-video`	`'5' \| '10'`	discrete
`fal-ai/kling-video/v3/pro/{text,image}-to-video`	`'3'` … `'15'`	discrete
`fal-ai/pika/v2.2/text-to-video`	`'5' \| '10'`	discrete
`fal-ai/ltx-2.3/{text,image}-to-video` (+ `/fast`)	`'6' \| '8' \| '10'`	discrete
`fal-ai/luma-dream-machine/ray-2`	`'5s' \| '9s'`	discrete
`fal-ai/veo3.1`, `fal-ai/veo3.1/fast` (+ `/image-to-video`), `fal-ai/veo3` (+ `/image-to-video`)	`'4s' \| '6s' \| '8s'`	discrete
`fal-ai/wan-25-preview/text-to-video`	`'2'` … `'15'`	discrete
`fal-ai/minimax/video-01`	수락되지 않음	`{ kind: 'none' }`
`fal-ai/hunyuan-video-v1.5/text-to-video`	수락되지 않음 (`num_frames`)	`{ kind: 'none' }`

import { generateVideo } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

const adapter = falVideo("fal-ai/veo3.1");
adapter.availableDurations(); // { kind: 'discrete', values: ['4s', '6s', '8s'] }
adapter.snapDuration(7); // '6s'

await generateVideo({
  adapter,
  prompt: "A timelapse of a city skyline at dusk",
  duration: adapter.snapDuration(7),
});

큐레이션되지 않은 모델도 엔드포인트가 해당 필드를 선언하면 SDK에서 duration 타입을 가져오지만, 런타임 맵에 추가되기 전까지 availableDurations()는 { kind: 'none' }을 반환합니다.

텍스트 음성 변환

텍스트 음성 변환은 generateSpeech() 활동과 함께 falSpeech()를 사용합니다. 어댑터는 fal의 CDN에서 생성된 오디오를 가져와 TTSResult 계약에 맞도록 base64 인코딩 데이터로 반환합니다.

import { generateSpeech } from "@tanstack/ai";
import { falSpeech } from "@tanstack/ai-fal";

const result = await generateSpeech({
  adapter: falSpeech("fal-ai/kokoro/american-english"),
  text: "Hello from fal!",
  voice: "af_heart",
  speed: 1.0,
});

// result.audio is a base64-encoded string
console.log(result.format); // e.g. "wav"
console.log(result.contentType); // e.g. "audio/wav"

Google Gemini 3.1 Flash TTS

Google의 최신 TTS 모델(fal-ai/gemini-3.1-flash-tts)은 80개 이상의 언어를 지원하며 표현을 세밀하게 제어하는 세분화된 오디오 태그를 도입합니다. 텍스트에 화자 태그와 스타일 지시어를 직접 삽입할 수 있습니다.

import { generateSpeech } from "@tanstack/ai";
import { falSpeech } from "@tanstack/ai-fal";

const result = await generateSpeech({
  adapter: falSpeech("fal-ai/gemini-3.1-flash-tts"),
  text: "[warm, enthusiastic] Welcome to TanStack AI! [pause] Let's build something great.",
  voice: "Kore",
});

참고: 이 모델은 @fal-ai/client@1.9.1의 타입 맵보다 최신이므로 modelOptions의 자동 완성이 제공되지 않습니다. 호출은 계속 작동합니다. fal 어댑터는 모든 모델 ID를 문자열로 허용합니다. fal의 SDK 타입이 업데이트되면 타입 안전 자동 완성도 제공됩니다.

ElevenLabs v3

import { generateSpeech } from "@tanstack/ai";
import { falSpeech } from "@tanstack/ai-fal";

const result = await generateSpeech({
  adapter: falSpeech("fal-ai/elevenlabs/tts/eleven-v3"),
  text: "Welcome to TanStack AI.",
  modelOptions: {
    voice: "Rachel",
    stability: 0.5,
  },
});

전사

음성-텍스트 변환은 generateTranscription() 활동과 함께 falTranscription()을 사용합니다. audio 입력은 URL 문자열, Blob, File 또는 ArrayBuffer를 허용하며, 업로드를 위해 ArrayBuffer는 자동으로 Blob으로 래핑됩니다.

import { generateTranscription } from "@tanstack/ai";
import { falTranscription } from "@tanstack/ai-fal";

const result = await generateTranscription({
  adapter: falTranscription("fal-ai/whisper"),
  audio: "https://example.com/recording.mp3",
  language: "en",
});

console.log(result.text);
console.log(result.language);

// When the model returns word/segment timestamps, they're mapped to result.segments
for (const segment of result.segments ?? []) {
  console.log(`[${segment.start}s → ${segment.end}s] ${segment.text}`);
}

오디오 생성(음악 및 음향 효과)

음악 및 음향 효과 생성은 generateAudio() 활동과 함께 falAudio()를 사용합니다. TTS와 달리 결과는 result.audio.url의 URL로 반환됩니다(원시 바이트가 필요하면 직접 가져올 수 있습니다).

import { generateAudio } from "@tanstack/ai";
import { falAudio } from "@tanstack/ai-fal";

// Music generation with MiniMax Music 2.6 (latest)
const music = await generateAudio({
  adapter: falAudio("fal-ai/minimax-music/v2.6"),
  prompt: "City Pop, 80s retro, groovy synth bass, warm female vocal, 104 BPM, nostalgic urban night",
});

console.log(music.audio.url);

import { generateAudio } from "@tanstack/ai";
import { falAudio } from "@tanstack/ai-fal";

// DiffRhythm with explicit lyrics
const lyrical = await generateAudio({
  adapter: falAudio("fal-ai/diffrhythm"),
  prompt: "An upbeat electronic track with synths",
  modelOptions: {
    lyrics: "[verse]\nHello world\n[chorus]\nLa la la",
  },
});

import { generateAudio } from "@tanstack/ai";
import { falAudio } from "@tanstack/ai-fal";

// Sound effects
const sfx = await generateAudio({
  adapter: falAudio("fal-ai/elevenlabs/sound-effects/v2"),
  prompt: "Thunderclap with rain",
  duration: 5,
});

모델	설명
`fal-ai/nano-banana-pro`	빠르고 고품질의 이미지 생성 (4K)
`fal-ai/flux-2/klein/9b`	향상된 사실감, 날카로운 텍스트 생성
`fal-ai/z-image/turbo`	초고속 6B 파라미터 모델
`xai/grok-imagine-image`	프롬프트 향상을 지원하는 xAI의 고품질 미적 이미지

모델	Mode	설명
`fal-ai/kling-video/v2.6/pro/text-to-video`	텍스트에서 비디오	고품질 텍스트에서 비디오
`fal-ai/kling-video/v2.6/pro/image-to-video`	이미지에서 비디오	Kling 을 사용하여 이미지를 애니메이션화합니다
`fal-ai/veo3.1`	텍스트에서 비디오	Google Veo 텍스트에서 비디오
`fal-ai/veo3.1/image-to-video`	이미지에서 비디오	Google Veo 이미지에서 비디오
`xai/grok-imagine-video/text-to-video`	텍스트에서 비디오	xAI 텍스트에서 비디오
`xai/grok-imagine-video/image-to-video`	이미지에서 비디오	xAI 이미지를 비디오로 애니메이션화합니다
`fal-ai/ltx-2/text-to-video/fast`	텍스트에서 비디오	빠른 텍스트에서 비디오
`fal-ai/ltx-2/image-to-video/fast`	이미지에서 비디오	빠른 이미지에서 비디오 애니메이션

모델	설명
`fal-ai/gemini-3.1-flash-tts`	신규 — 80개 이상의 언어와 표현형 오디오 태그를 지원하는 Google의 대표 TTS
`fal-ai/elevenlabs/tts/eleven-v3`	ElevenLabs v3 다성감정 표현형 텍스트 음성 변환
`fal-ai/elevenlabs/tts/turbo-v2.5`	저지연 ElevenLabs 텍스트 음성 변환
`fal-ai/minimax/speech-2.6-hd`	MiniMax HD 음성 합성
`fal-ai/minimax/speech-2.6-turbo`	MiniMax 저지연 버전
`fal-ai/kokoro/american-english`	Kokoro 다국어 텍스트 음성 변환 — 또한 `british-english`, `french`, `spanish`, `italian`, `japanese`, `mandarin-chinese`, `hindi`, `brazilian-portuguese`
`fal-ai/inworld-tts`	Inworld TTS-1.5 Max
`fal-ai/chatterbox/text-to-speech/multilingual`	Chatterbox 다국어 텍스트 음성 변환
`fal-ai/dia-tts`	Dia 표현형 대화 텍스트 음성 변환
`fal-ai/orpheus-tts`	Orpheus 오픈소스 텍스트 음성 변환
`fal-ai/f5-tts`	F5-TTS 음성 복제
`fal-ai/vibevoice/7b`	VibeVoice 7B 대화형 텍스트 음성 변환

모델	설명
`fal-ai/whisper`	fal 인프라의 OpenAI Whisper
`fal-ai/wizper`	단어 단위 타임스탬프를 갖는 Faster-whisper 변형
`fal-ai/speech-to-text/turbo`	화자 분리 기능이 있는 Turbo STT
`fal-ai/elevenlabs/speech-to-text`	ElevenLabs STT

모델	모드	설명
`fal-ai/minimax-music/v2.6`	음악	신규 — 프롬프트로 보컬과 기악을 포함한 전체 곡을 생성하는 MiniMax Music 2.6
`fal-ai/minimax-music/v2.5`	음악	MiniMax Music 2.5
`fal-ai/minimax-music/v2`	음악	`lyrics_prompt`을 지원하는 MiniMax Music v2
`fal-ai/diffrhythm`	음악	DiffRhythm — 프롬프트 + 가사
`fal-ai/lyria2`	음악	Google Lyria 2 고음질 음악
`fal-ai/stable-audio-25/text-to-audio`	음악 / 오디오	Stability AI Stable Audio 2.5
`fal-ai/mmaudio-v2/text-to-audio`	오디오	MMAudio v2 텍스트-오디오 변환
`fal-ai/elevenlabs/sound-effects/v2`	음향 효과	ElevenLabs 음향 효과 생성
`fal-ai/beatoven/sound-effect-generation`	음향 효과	Beatoven 전문 음향 효과
`fal-ai/thinksound`	오디오	Thinksound 추론 기반 오디오 생성

환경 변수

fal.ai에서 API 키를 만들고 환경에 설정합니다.

FAL_KEY=your-fal-api-key

API 참조

`falImage(model, config?)`

FAL_KEY 환경 변수 또는 명시적 구성을 사용해 fal.ai 이미지 어댑터를 만듭니다.

매개변수:

model - fal.ai 모델 ID(예: "fal-ai/flux/dev")
config.apiKey? - fal.ai API 키 (FAL_KEY 환경 변수로 자동 대체)
config.proxyUrl? - 클라이언트 측 사용용 프록시 URL

반환값: generateImage()와 함께 사용하는 FalImageAdapter 인스턴스입니다.

`falVideo(model, config?)`

FAL_KEY 환경 변수 또는 명시적 구성을 사용해 fal.ai 동영상 어댑터를 만듭니다.

Parameters:

model - fal.ai 모델 ID(예: "fal-ai/kling-video/v2.6/pro/text-to-video")
config.apiKey? - fal.ai API 키 (FAL_KEY 환경 변수로 자동 대체)
config.proxyUrl? - 클라이언트 측 사용용 프록시 URL

반환값: generateVideo() 및 getVideoJobStatus()와 함께 사용하는 FalVideoAdapter 인스턴스입니다.

`falSpeech(model, config?)`

fal.ai 텍스트 음성 변환 어댑터를 만듭니다.

Parameters:

model - fal.ai TTS 모델 ID(예: "fal-ai/kokoro/american-english")
config.apiKey? - fal.ai API 키 (FAL_KEY 환경 변수로 자동 대체)
config.proxyUrl? - 클라이언트 측 사용용 프록시 URL

반환값: generateSpeech()와 함께 사용하는 FalSpeechAdapter 인스턴스입니다. 어댑터는 fal에서 생성된 오디오 URL을 가져와 result.audio에 base64로 반환합니다.

`falTranscription(model, config?)`

fal.ai 전사(음성-텍스트 변환) 어댑터를 만듭니다.

Parameters:

model - fal.ai STT 모델 ID(예: "fal-ai/whisper")
config.apiKey? - fal.ai API 키 (FAL_KEY 환경 변수로 자동 대체)
config.proxyUrl? - 클라이언트 측 사용용 프록시 URL

반환값: generateTranscription()과 함께 사용하는 FalTranscriptionAdapter 인스턴스입니다.

`falAudio(model, config?)`

fal.ai 오디오 생성 어댑터(음악 및 음향 효과)를 만듭니다.

Parameters:

model - fal.ai 오디오 모델 ID(예: "fal-ai/diffrhythm", "fal-ai/minimax-music/v2")
config.apiKey? - fal.ai API 키 (FAL_KEY 환경 변수로 자동 대체)
config.proxyUrl? - 클라이언트 측 사용용 프록시 URL

반환값: generateAudio()와 함께 사용하는 FalAudioAdapter 인스턴스입니다. 결과에는 result.audio.url의 URL이 포함됩니다.

`getFalApiKeyFromEnv()`

FAL_KEY 환경 변수를 읽습니다. 설정되지 않으면 오류를 발생시킵니다.

반환값: API 키 문자열입니다.

`configureFalClient(config?)`

기반이 되는 @fal-ai/client를 구성합니다. 어댑터 생성자가 자동으로 호출합니다. proxyUrl이 제공되면 이를 사용하고, 그렇지 않으면 API 키로 자격 증명을 설정합니다.

제한 사항

텍스트/chat 미지원 — chat()에는 OpenAI, Anthropic, Gemini 또는 다른 텍스트 어댑터를 사용합니다.
도구 미지원 — 도구 정의는 미디어 생성에 적용되지 않습니다.
요약 미지원 — summarize()에는 텍스트 어댑터를 사용합니다.
동영상은 실험적임 — 동영상 생성 API는 향후 릴리스에서 변경될 수 있습니다.

다음 단계

Getting Started - 기본 사항을 알아봅니다
Other Adapters - 다른 제공자를 살펴봅니다

fal.ai

설치

문자열 리터럴을 사용한 타입 안전성

기본 사용법

기본 사용법 - 사용자 지정 API 키

구성

예제: 이미지 생성

예제: 모델 옵션을 사용한 이미지

이미지 크기 옵션

동영상 생성(실험적)

예제: 텍스트에서 동영상으로

예제: 이미지에서 동영상으로

텍스트 음성 변환

Google Gemini 3.1 Flash TTS

ElevenLabs v3

전사

오디오 생성(음악 및 음향 효과)

인기 모델

이미지 모델

동영상 모델

텍스트 음성 변환 모델

전사 모델

오디오 / 음악 모델

환경 변수

API 참조

`falImage(model, config?)`

`falVideo(model, config?)`

`falSpeech(model, config?)`

`falTranscription(model, config?)`

`falAudio(model, config?)`

`getFalApiKeyFromEnv()`

`configureFalClient(config?)`

제한 사항

다음 단계

설치​

문자열 리터럴을 사용한 타입 안전성​

기본 사용법​

기본 사용법 - 사용자 지정 API 키​

구성​

예제: 이미지 생성​

예제: 모델 옵션을 사용한 이미지​

이미지 크기 옵션​

동영상 생성(실험적)​

예제: 텍스트에서 동영상으로​

예제: 이미지에서 동영상으로​

텍스트 음성 변환​

Google Gemini 3.1 Flash TTS​

ElevenLabs v3​

전사​

오디오 생성(음악 및 음향 효과)​

인기 모델​

이미지 모델​

동영상 모델​

텍스트 음성 변환 모델​

전사 모델​

오디오 / 음악 모델​

환경 변수​

API 참조​

falImage(model, config?)​

falVideo(model, config?)​

falSpeech(model, config?)​

falTranscription(model, config?)​

falAudio(model, config?)​

getFalApiKeyFromEnv()​

configureFalClient(config?)​

제한 사항​

다음 단계​

설치

문자열 리터럴을 사용한 타입 안전성

기본 사용법

기본 사용법 - 사용자 지정 API 키

구성

예제: 이미지 생성

예제: 모델 옵션을 사용한 이미지

이미지 크기 옵션

동영상 생성(실험적)

예제: 텍스트에서 동영상으로

예제: 이미지에서 동영상으로

텍스트 음성 변환

Google Gemini 3.1 Flash TTS

ElevenLabs v3

전사

오디오 생성(음악 및 음향 효과)

인기 모델

이미지 모델

동영상 모델

텍스트 음성 변환 모델

전사 모델

오디오 / 음악 모델

환경 변수

API 참조

`falImage(model, config?)`

`falVideo(model, config?)`

`falSpeech(model, config?)`

`falTranscription(model, config?)`

`falAudio(model, config?)`

`getFalApiKeyFromEnv()`

`configureFalClient(config?)`

제한 사항

다음 단계