Replicate / fal.ai 설정 가이드
Replicate와 fal.ai는 '모델 호스팅 API 플랫폼'에 가깝습니다. 이미지, 오디오, 비디오 등의 다양한 모델을 호출할 수 있지만, 모든 모델이 동일한 파라미터 규격을 사용하지는 않습니다. 초보자라면 먼저 구체적인 모델을 선택한 후, 해당 모델 페이지에서 제공하는 입력 필드를 꼼꼼히 확인해야 합니다.
공식 정보 다운로드 및 문서는 공식 사이트를 기준으로 합니다.
일반 AI 제공자와 다른 점
| 플랫폼 | 사전 준비 항목 | 주의 사항 |
|---|---|---|
| Replicate | API Token, 모델 페이지, 입력 파라미터 | 공식 Node SDK는 기본적으로 REPLICATE_API_TOKEN 환경 변수를 읽습니다. 모델마다 입력 필드가 서로 다릅니다. |
| fal.ai | FAL_KEY, 모델 ID, 입력 파라미터 | 공식 JS 클라이언트는 기본적으로 FAL_KEY 환경 변수를 읽습니다. 마찬가지로 특정 모델 페이지의 필드를 확인해야 합니다. |
| 일반 대화형 AI 제공자 | Key, Base URL, 모델명 | 주로 텍스트/멀티모달 대화에 집중되어 있어, 모든 이미지 및 비디오 모델을 지원하는 것은 아닙니다. |
모델별 상세 페이지 먼저 이해하기
| 페이지 필드 | 의미 | 작성 방법 |
|---|---|---|
| Model ID / Version | 호출할 구체적인 모델 식별자 | Replicate는 주로 모델 페이지에 안내된 owner/model 또는 owner/model:version 형식을 사용합니다. fal.ai는 모델 페이지의 ID를 그대로 입력합니다. |
| Input schema | 해당 모델이 요구하는 입력 필드 목록 | 모델 페이지에 맞춰 각 항목을 입력해야 하며, 다른 모델의 필드를 그대로 복사해 사용하면 안 됩니다. |
| Output | 반환되는 결과의 형식 | 이미지 URL, 비디오 URL, 배열, 작업 객체 등 다양합니다. 호출 후 반환 구조에 맞춰 결과를 추출해야 합니다. |
| Example code | 현재 모델에 맞춰 자동 생성된 공식 호출 예제 | 모델 페이지의 현재 예제 코드를 먼저 복사한 뒤, 본인의 Key와 입력 값으로 교체하는 방식을 권장합니다. |
요청 예시
두 플랫폼의 작성 방식을 혼용하지 마세요. 사용 중인 플랫폼의 탭을 선택하고, 본인의 Key, 모델 ID, 입력 필드만 변경하여 사용하세요.
Replicate 추론(Prediction) 작업 생성 예제
import Replicate from "replicate"; const replicate = new Replicate({ auth: process.env.REPLICATE_API_TOKEN }); const output = await replicate.run("owner/model:version from the model page", { input: { prompt: "A clean product showcase video", duration: 5 } }); console.log(output);fal.ai 모델 호출 예제
import { fal } from "@fal-ai/client"; fal.config({ credentials: process.env.FAL_KEY }); const result = await fal.subscribe("MODEL_ID_FROM_THE_MODEL_PAGE", { input: { prompt: "A photorealistic product poster", image_size: "square_hd" }, logs: true }); console.log(result.data);필드 확인 및 트러블슈팅
이러한 플랫폼에서 가장 중요한 것은 '해당 모델의 상세 페이지'입니다. 단순히 플랫폼 Key만 복사하는 데 그치지 말고, 반드시 모델 페이지에 정의된 입력 필드에 맞춰 작성하세요.
| 오류 현상 | 일반적인 원인 | 해결 방법 |
|---|---|---|
| Model not found | 모델 ID, 버전 번호 또는 네임스페이스가 잘못되었습니다. | 모델 페이지에서 전체 호출 경로(이름)를 정확히 복사해 붙여넣으세요. |
| Input field error | 필드명, 데이터 타입 또는 필수 항목이 현재 모델 사양과 일치하지 않습니다. | 모델 페이지의 Input schema를 확인하고 누락되거나 잘못된 항목을 수정하세요. |
| Returned result is empty | 작업이 아직 완료되지 않았거나, 참조하려는 경로에 출력 필드가 없습니다. | 먼저 반환된 전체 결과를 출력(print/console.log)해 본 뒤, 출력 구조에 맞춰 URL이나 파일 경로를 추출하세요. |