fal-api-reference

## Quick Reference

| Method | Use Case | Code |
|--------|----------|------|
| `fal.subscribe()` | Queue-based (recommended) | `await fal.subscribe("model", { input })` |
| `fal.run()` | Fast endpoints (<30s) | `await fal.run("model", { input })` |
| `fal.stream()` | Progressive output | `for await (const event of stream) {}` |
| `fal.realtime.connect()` | WebSocket interactive | `fal.realtime.connect("model", callbacks)` |

| Queue Method | Purpose |
|--------------|---------|
| `fal.queue.submit()` | Submit job, get request_id |
| `fal.queue.status()` | Check job status |
| `fal.queue.result()` | Get completed result |
| `fal.queue.cancel()` | Cancel pending job |

| Auth | Header | Format |
|------|--------|--------|
| API Key | `Authorization` | `Key YOUR_FAL_KEY` |

## When to Use This Skill

Use for **API integration fundamentals**:
- Setting up fal.ai client in JavaScript/TypeScript
- Setting up fal_client in Python
- Choosing between subscribe, run, and stream methods
- Implementing webhook callbacks
- Uploading files to fal.media CDN

**Related skills:**
- For model selection: see `fal-model-guide`
- For performance optimization: see `fal-optimization`
- For custom model deployment: see `fal-serverless-guide`

---

# fal.ai API Reference

Complete API reference for fal.ai client libraries and REST endpoints.

## Client Libraries

### JavaScript/TypeScript (@fal-ai/client)

```bash
npm install @fal-ai/client
```

#### Configuration

```typescript
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"
});
```

#### Core Methods

**fal.subscribe(endpoint, options)**
Queue-based execution with automatic polling. Recommended for most use cases.

```typescript
const result = await fal.subscribe("fal-ai/flux/dev", {
  input: {
    prompt: "A beautiful landscape"