fal-api-reference

クイックリファレンス

メソッド	ユースケース	コード
fal.subscribe()	キューベース（推奨）	await fal.subscribe("model", { input })
fal.run()	高速なエンドポイント（<30s）	await fal.run("model", { input })
fal.stream()	段階的な出力	for await (const event of stream) {}
fal.realtime.connect()	WebSocket による対話型接続	fal.realtime.connect("model", callbacks)

キューメソッド	目的
fal.queue.submit()	ジョブを送信し、request_id を取得
fal.queue.status()	ジョブのステータスを確認
fal.queue.result()	完了した結果を取得
fal.queue.cancel()	保留中のジョブをキャンセル

認証	ヘッダー	形式
API キー	Authorization	Key YOUR_FAL_KEY

このスキルを使用する場面

API 統合の基本には、以下の用途で使用します。

• JavaScript/TypeScript で fal.ai クライアントをセットアップする
• Python で fal_client をセットアップする
• subscribe、run、stream メソッドから選択する
• Webhook コールバックを実装する
• ファイルを fal.media CDN にアップロードする

関連スキル：

• モデルの選択については、fal-model-guide を参照してください
• パフォーマンスの最適化については、fal-optimization を参照してください
• カスタムモデルのデプロイについては、fal-serverless-guide を参照してください

---

fal.ai API リファレンス

fal.ai クライアントライブラリと REST エンドポイントの完全な API リファレンスです。

クライアントライブラリ

JavaScript/TypeScript (@fal-ai/client)

npm install @fal-ai/client

設定

import { fal } from "@fal-ai/client";

// Configure credentials (reads FAL_KEY from environment by default)
fal.config({
  credentials: process.env.FAL_KEY,
  // Optional: custom proxy URL for browser apps
  proxyUrl: "https://your-server.com/api/fal-proxy"
});

コアメソッド

fal.subscribe(endpoint, options) 自動ポーリングによるキューベースの実行です。ほとんどのユースケースで推奨されます。

const result = await fal.subscribe("fal-ai/flux/dev", {
  input: {
    prompt: "A beautiful landscape"
  },
  logs: true,
  pollInterval: 1000,  // Poll every second (default: 1000)
  onQueueUpdate: (update) => {
    // update.status: "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED"
    if (update.status === "IN_PROGRESS") {
      update.logs?.forEach(log => console.log(log.message));
    }
  }
});

fal.run(endpoint, options) 直接／同期実行です。高速なエンドポイント（< 30 秒）でのみ使用してください。

const result = await fal.run("fal-ai/fast-sdxl", {
  input: { prompt: "A cat" }
});

fal.stream(endpoint, options) 段階的な出力のためのサーバー送信イベントです。

const stream = await fal.stream("fal-ai/flux/dev", {
  input: { prompt: "A landscape" }
});

for await (const event of stream) {
  console.log("Progress:", event);
}

const finalResult = await stream.done();

fal.realtime.connect(endpoint, callbacks) リアルタイム対話型アプリケーション向けの WebSocket 接続です。

const connection = fal.realtime.connect("fal-ai/lcm-sd15-i2i", {
  connectionKey: "unique-session-id",
  throttleInterval: 128,  // Debounce inputs (ms)
  onResult: (result) => console.log("Generated:", result),
  onError: (error) => console.error("Error:", error),
  onOpen: () => console.log("Connected"),
  onClose: () => console.log("Disconnected")
});

// Send inputs
connection.send({
  prompt: "A cute cat",
  image_url: "https://example.com/base.jpg"
});

// Close when done
connection.close();

キューメソッド

高度な制御のための手動キュー管理です。

// Submit to queue
const { request_id } = await fal.queue.submit("fal-ai/flux/dev", {
  input: { prompt: "Test" },
  webhookUrl: "https://your-server.com/webhook"  // Optional
});

// Check status
const status = await fal.queue.status("fal-ai/flux/dev", {
  requestId: request_id,
  logs: true
});
// status.status: "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED"

// Get result (blocks until complete)
const result = await fal.queue.result("fal-ai/flux/dev", {
  requestId: request_id
});

// Cancel request
await fal.queue.cancel("fal-ai/flux/dev", {
  requestId: request_id
});

ストレージメソッド

ファイルを fal.media CDN にアップロードします。

// Upload File object
const file = new File([blob], "image.png", { type: "image/png" });
const url = await fal.storage.upload(file);

// Upload from URL
const response = await fetch("https://example.com/image.jpg");
const blob = await response.blob();
const url = await fal.storage.upload(new File([blob], "image.jpg"));

Python (fal-client)

pip install fal-client

同期 API

import fal_client

# Simple run
result = fal_client.run(
    "fal-ai/flux/dev",
    arguments={
        "prompt": "A beautiful landscape",
        "image_size": "landscape_16_9"
    }
)

# Subscribe with status updates
def on_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
            print(log["message"])

result = fal_client.subscribe(
    "fal-ai/flux/dev",
    arguments={"prompt": "Test"},
    with_logs=True,
    on_queue_update=on_update
)

# Manual queue management
handler = fal_client.submit(
    "fal-ai/flux/dev",
    arguments={"prompt": "Test"}
)
print(f"Request ID: {handler.request_id}")
status = handler.status()  # Check status
result = handler.get()     # Block until complete

非同期 API

import asyncio
import fal_client

async def generate():
    # Async run
    result = await fal_client.run_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"}
    )

    # Async subscribe
    result = await fal_client.subscribe_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"},
        with_logs=True
    )

    # Async queue management
    handler = await fal_client.submit_async(
        "fal-ai/flux/dev",
        arguments={"prompt": "Test"}
    )
    status = await handler.status_async()
    result = await handler.get_async()

    return result

result = asyncio.run(generate())

ファイルのアップロード

# Upload file from path
url = fal_client.upload_file("path/to/image.png")

# Upload bytes
with open("image.png", "rb") as f:
    url = fal_client.upload(f.read(), "image/png")

# Encode as data URL (small files only)
data_url = fal_client.encode_file("small_image.png")

REST API

ベース URL

用途	URL パターン
キュー送信	https://queue.fal.run/{model_id}
キューステータス	https://queue.fal.run/{model_id}/requests/{request_id}/status
キュー結果	https://queue.fal.run/{model_id}/requests/{request_id}
キャンセル	https://queue.fal.run/{model_id}/requests/{request_id}/cancel
直接実行	https://fal.run/{model_id}
WebSocket	wss://fal.run/{model_id}

認証

Authorization: Key YOUR_FAL_KEY

キューワークフロー

# 1. Submit to queue
curl -X POST "https://queue.fal.run/fal-ai/flux/dev" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful landscape",
    "image_size": "landscape_16_9"
  }'

# Response:
# {
#   "request_id": "abc123-def456",
#   "status": "IN_QUEUE",
#   "queue_position": 0
# }

# 2. Check status
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123-def456/status" \
  -H "Authorization: Key $FAL_KEY"

# Response (in progress):
# {
#   "status": "IN_PROGRESS",
#   "logs": [{"message": "Loading model...", "timestamp": "..."}]
# }

# Response (completed):
# {
#   "status": "COMPLETED"
# }

# 3. Get result
curl "https://queue.fal.run/fal-ai/flux/dev/requests/abc123-def456" \
  -H "Authorization: Key $FAL_KEY"

# Response:
# {
#   "images": [{"url": "https://fal.media/...", "width": 1024, "height": 576}],
#   "seed": 12345,
#   "prompt": "A beautiful landscape"
# }

Webhook

Webhook URL を指定して送信すると、POST 経由で結果を受け取れます。

curl -X POST "https://queue.fal.run/fal-ai/flux/dev" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Test",
    "webhook_url": "https://your-server.com/webhook"
  }'

Webhook ペイロード：

{
  "request_id": "abc123",
  "status": "COMPLETED",
  "payload": {
    "images": [{"url": "https://fal.media/..."}]
  }
}

直接実行

高速なエンドポイント（< 30 秒）向けです。

curl -X POST "https://fal.run/fal-ai/fast-sdxl" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat"}'

よく使われるモデルパラメーター

FLUX モデル

interface FluxInput {
  prompt: string;                    // Required
  image_size?:
    | "square_hd"      // 1024x1024
    | "square"         // 512x512
    | "portrait_4_3"   // 768x1024
    | "portrait_16_9"  // 576x1024
    | "landscape_4_3"  // 1024x768
    | "landscape_16_9" // 1024x576
    | { width: number; height: number };
  num_inference_steps?: number;      // 1-50, default: 28
  guidance_scale?: number;           // 1-20, default: 3.5
  num_images?: number;               // 1-4, default: 1
  seed?: number;                     // For reproducibility
  enable_safety_checker?: boolean;   // Default: true
  output_format?: "jpeg" | "png";    // Default: jpeg
  sync_mode?: boolean;               // Wait for completion
}

interface FluxOutput {
  images: Array<{
    url: string;
    width: number;
    height: number;
    content_type: string;
  }>;
  seed: number;
  prompt: string;
  has_nsfw_concepts?: boolean[];
  timings?: {
    inference: number;
  };
}

動画モデル

interface VideoInput {
  prompt: string;
  negative_prompt?: string;
  duration?: number;          // seconds
  aspect_ratio?: "16:9" | "9:16" | "1:1" | "4:3" | "21:9";
  cfg_scale?: number;         // 0.0-1.0
  seed?: number;
  // Model-specific options...
}

interface VideoOutput {
  video: {
    url: string;
    content_type: string;
    file_size?: number;
  };
  audio?: {
    url: string;
  };
  seed: number;
}

音声モデル（Whisper）

interface WhisperInput {
  audio_url: string;
  task?: "transcribe" | "translate";
  language?: string;         // ISO code
  chunk_level?: "segment";
  version?: "3";
}

interface WhisperOutput {
  text: string;
  chunks?: Array<{
    text: string;
    timestamp: [number, number];
  }>;
}

エラーレスポンス

// 400 Bad Request - Validation error
{
  "detail": "Invalid input",
  "errors": [
    {"field": "prompt", "message": "Field is required"}
  ]
}

// 401 Unauthorized
{
  "detail": "Invalid API key"
}

// 429 Too Many Requests
{
  "detail": "Rate limit exceeded",
  "retry_after": 60
}

// 500 Internal Server Error
{
  "detail": "Internal server error",
  "request_id": "abc123"
}

レート制限

• レート制限はサブスクリプションのティアによって異なります
• 429 レスポンスに対して指数バックオフを実装します
• 大量のリクエストを扱うアプリケーションでは Webhook を使用します
• エンタープライズ向けのレート制限については fal.ai にお問い合わせください

SDK バージョン

ライブラリ	最新バージョン	インストール
@fal-ai/client	0.15+	npm install @fal-ai/client
fal-client (Python)	0.4+	pip install fal-client
fal (Serverless)	0.13+	pip install fal

最新の API ドキュメントと更新情報は、https://docs.fal.ai を必ずご確認ください。