Fal.ai API 사용 튜토리얼 (1)

Fal.ai는 GitHub·Google SSO로 1분 만에 가입하고, 대시보드에서 결제 수단과 API Key만 넣으면 곧바로 수백 여 종의 이미지·영상 생성 모델을 호출할 수 있는 GPU Serverless 플랫폼입니다.

요금은 GPU 초당 또는 결과물(초·메가픽셀) 단가로 과금되므로, 간단한 실험부터 대규모 배포까지 유연하게 확장할 수 있습니다.

아래 순서를 그대로 따라 하면 ― 가입 → 빌링 설정 → Key 발급 → 모델 탐색 → 동영상 생성 요청 ― 10 분 안에 PoC를 띄울 수 있습니다.

1. 가입 & 로그인

fal.ai/login 접속 → Continue with GitHub or Google 버튼 클릭 (SSO)

최초 로그인 시 이메일·이용약관만 확인하면 즉시 계정이 생성됩니다.

2FA 활성화 GitHub/Google 계정이면 별도 메일 인증 없이 통과됩니다.

TIP 엔터프라이즈 조직은 SAML SSO 메뉴(“Continue with SSO”)를 통해 자체 IdP 연동도 가능합니다. (fal.ai)

2. 빌링(Billing) 설정

단계	설명
결제 메뉴 이동	우측 상단 프로필 ▸ Billing (`/dashboard/billing`)
결제수단 추가	신용카드 / 청구서(Invoice) 중 선택. 대량 사용 시 문의하면 인보이스 결제 전환 가능.
가격 구조 이해	• GPU 과금 : A100 $0.99/h, H100 $1.89/h 등 초당 요금 • Output 과금 : 예) Kling 2.0 Master 1 초 $0.28 (5 초 1 건 $1.40)
크레딧 사용	가입 시 소량 무료 크레딧 지급. 다 쓰면 카드/인보이스에서 자동 차감.
비용 모니터링	Billing 페이지 그래프 + 요청별 메트릭으로 실시간 확인.

Pricing

확인하러 가기

3. API Key 발급

대시보드 Keys (/dashboard/keys) 진입 → Create Key 버튼 클릭

API (모델 호출 전용) Scope 선택 후 생성

4. 모델 조회 방법

4-1. Model Gallery

Explore → Model Gallery → Search trends 메뉴에서 텍스트·음성·영상 등 카테고리별 API를 필터링할 수 있습니다.

4-2. API 탭 확인

원하는 모델 카드 클릭 → API 탭에서 모델 ID(예: fal-ai/kling-video/v2/master/image-to-video), 입력 스키마, 샘플 코드가 자동 생성됩니다.

4-3. 호출 방식

방식	URL	특징
동기 (Sync)	`https://fal.run/{model_id}`	30-60 초 이하 빠른 모델에 적합
큐 (Async)	`https://queue.fal.run/{model_id}`	장시간 작업·대량 트래픽 처리, 상태 확인 API 제공
WebSocket	`wss://ws.fal.run/{model_id}`	실시간 스트리밍 결과 필요 시

5. 동영상 생성 모델 호출 (HTTP 예시)

5-1. 준비하기

모델 선택 : 예) Kling 2.0 Master fal-ai/kling-video/v2/master/image-to-video (고품질 5-10 초 영상)

입력 요구 : prompt, image_url 필수 + duration, cfg_scale 옵션

5-2. CURL (Queue 방식)


# ① 요청 등록
curl -X POST https://queue.fal.run/fal-ai/kling-video/v2/master/image-to-video \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "A futuristic city at sunset, cinematic camera pan",
        "image_url": "https://example.com/ref.jpg",
        "duration": "5"
      }'

# 응답 예시
# {
#   "request_id": "80e732af-660e-45cd-bd63-580e4f2a94cc",
#   "status_url": "https://queue.fal.run/fal-ai/kling-video/v2/master/image-to-video/requests/80e732af-660e-45cd-bd63-580e4f2a94cc/status",
#   "response_url": "..."
# }

# ② 진행 상황 확인
curl -X GET \
  https://queue.fal.run/fal-ai/kling-video/v2/master/image-to-video/requests/80e732af-660e-45cd-bd63-580e4f2a94cc/status

# ③ 결과 가져오기 (status가 COMPLETED 일 때)
curl -X GET \
  https://queue.fal.run/fal-ai/kling-video/v2/master/image-to-video/requests/80e732af-660e-45cd-bd63-580e4f2a94cc

큐 엔드포인트·상태 값(IN_QUEUE, IN_PROGRESS, COMPLETED)·로그 활성화 방법은 공식 Queue 문서를 참고하세요. (docs.fal.ai)

5-3. 동기(Sync) 호출이 필요하다면


curl -X POST https://fal.run/fal-ai/kling-video/v2/master/image-to-video \
  -H "Authorization: Key $FAL_KEY" \
  -d '{"prompt":"...","image_url":"..."}'

단, 60 초 이상 걸리면 타임아웃이 날 수 있으므로 영상 모델은 Queue 방식을 권장합니다.

5-4. n8n HTTP Request 노드 구성 및 인증 설정

HTTP Request 노드 추가

HTTP Reuqest 노드의 “Import cURL” 버튼 클릭 → cURL Command 에 위에서 확인한 명령문 붙여넣기 → [ Import ] 버튼 클릭

Header Parameter 삭제

Authentication Type ( Generaic Credential Type ) → Generic Auth Type ( Header Auth ) → [ Create new credential ] 버튼 클릭

Credential 생성 창이 팝업되면 Auth Name, Name, Value를 입력해야함. Auth Name은 사용자가 자유롭게 구분할수 있도록 작성해도됨. but, Name과 Value는 아래 규칙을 따라야 함.

Name : Authorization
Value : Key [발급받은 API Key]

예) Key dEeJ/odIfrT7VYRVKQ1ZE6xE3DzPzhgbqmR0JNqwpBs=

인증 설정 완료

6. 추가 꿀팁

사용 상황	권장 기능
대량 비동기 작업	`webhookUrl` 파라미터로 완료 알림 받기
파일 직접 업로드	`fal.storage.upload()` 사용 시 URL 자동 생성
클라이언트 라이브러리	`npm i @fal-ai/client` 또는 `pip install fal-client` 로 간단 호출
비용 제어	Billing 페이지 그래프 + 요청별 metrics 점검 후 필요 시 요금 cap 설정

✅ 정리

SSO로 로그인 → 2. Billing 탭에서 카드 등록 & 무료 크레딧 확인 → 3. Keys 탭에서 API Key 발급 → 4. Model Gallery에서 ID 복사 → 5. curl 또는 SDK로 Queue 요청 후 status/result 조회.

이 순서를 따르면 Fal.ai의 최신 영상 생성 모델을 바로 프로덕션 워크플로에 통합할 수 있습니다. 🎬