Apus ships a bundled fal provider for hosted image, video, and music generation.

Getting started

Create a key at [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys).

```bash
apus onboard --auth-choice fal-api-key
```

Non-interactive setups can pass `--fal-api-key <key>` or export `FAL_KEY`.
Onboarding also sets `fal/fal-ai/flux/dev` as the default image model when
none is configured.

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/fal-ai/flux/dev",
        },
      },
    },
  },
}
```

Image generation

The bundled fal image-generation provider defaults to fal/fal-ai/flux/dev.

Edit requests (reference images via the shared image / images parameters) route to a per-model edit endpoint with per-model reference limits:

GPT Image 2.5

Select either variant:

• fal/openai/gpt-image-2.5/flare/text-to-image
• fal/openai/gpt-image-2.5/sunburst/text-to-image

References select the sibling /edit endpoint. You can also select fal/openai/gpt-image-2.5/flare/edit or fal/openai/gpt-image-2.5/sunburst/edit explicitly.

Both variants support quality: "low", "medium", "high", "xhigh", "max", or "auto". The fal default is high. They accept background: "transparent", "opaque", or "auto". For transparency, use outputFormat: "png" or "webp". These controls do not change older fal models.

Use size: "auto" or explicit dimensions such as 1536x864. Dimensions must be divisible by 16, with no edge above 3840 pixels. Total pixels must be 655,360-8,294,400, with an aspect ratio from 1:3 to 3:1. Apus converts aspect-ratio hints to valid dimensions. For example, aspectRatio: "3:2" produces 1536x1024. Use size to choose exact dimensions. Apus rejects invalid explicit sizes. These models reject resolution overrides. Edits without geometry hints keep fal's automatic size selection.

apus infer image generate \
  --model fal/openai/gpt-image-2.5/flare/text-to-image \
  --prompt "A simple red circle sticker" \
  --quality low --size 1024x1024 --json

apus infer image edit \
  --model fal/openai/gpt-image-2.5/sunburst/edit \
  --file /path/to/reference.png \
  --prompt "Keep the shape and change the color to blue" \
  --quality low --size auto --json

Krea 2

Krea 2 models use fal's native Krea payload schema. Apus sends aspect_ratio, creativity, and image_style_references instead of the generic image_size / edit-endpoint payload used by Flux. The model refs are:

• fal/krea/v2/medium/text-to-image
• fal/krea/v2/large/text-to-image

Use Medium for faster expressive illustration, anime, painting, and artistic styles. Use Large for slower photoreal, raw texture, film grain, and detailed looks. Krea defaults to fal.creativity: "medium"; supported values are raw, low, medium, and high.

Krea 2 exposes aspect ratio, not image_size, in fal's request schema. Prefer aspectRatio; Apus maps size to the closest supported Krea aspect ratio and rejects resolution for Krea rather than dropping it.

Use outputFormat: "png" when you want PNG output from fal models that expose output_format. Outside GPT Image 2.5, fal models do not declare a transparent-background control in Apus. They report background as an ignored override. Krea 2 endpoints do not expose an output_format request field through fal, so Apus rejects outputFormat overrides for Krea requests.

To use Krea 2 Medium:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/krea/v2/medium/text-to-image",
        },
      },
    },
  },
}

Video generation

The bundled fal video-generation provider defaults to fal/fal-ai/minimax/video-01-live.

**MiniMax (default):**

- `fal/fal-ai/minimax/video-01-live`

**HeyGen video-agent:**

- `fal/fal-ai/heygen/v2/video-agent`

**Kling and Wan:**

- `fal/fal-ai/kling-video/v2.1/master/text-to-video`
- `fal/fal-ai/wan/v2.2-a14b/text-to-video`
- `fal/fal-ai/wan/v2.2-a14b/image-to-video`

**Seedance 2.0:**

- `fal/bytedance/seedance-2.0/fast/text-to-video`
- `fal/bytedance/seedance-2.0/fast/image-to-video`
- `fal/bytedance/seedance-2.0/fast/reference-to-video`
- `fal/bytedance/seedance-2.0/text-to-video`
- `fal/bytedance/seedance-2.0/image-to-video`
- `fal/bytedance/seedance-2.0/reference-to-video`

MiniMax Live and HeyGen requests send only the prompt plus an optional
single reference image; other overrides are not forwarded. Seedance models
accept `aspectRatio`, `size`, `resolution`, durations of 4-15 seconds, and
an audio toggle.

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
        },
      },
    },
  },
}
```

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/reference-to-video",
        },
      },
    },
  },
}
```

Reference-to-video accepts up to 9 images, 3 videos, and 3 audio references
through the shared `video_generate` `images`, `videos`, and `audioRefs`
parameters, with at most 12 total reference files. Audio references require
at least one image or video reference in the same request.

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/fal-ai/heygen/v2/video-agent",
        },
      },
    },
  },
}
```

Music generation

The bundled fal plugin also registers a music-generation provider for the shared music_generate tool.

Use fal as the default music provider:

{
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "fal/fal-ai/minimax-music/v2.6",
        },
      },
    },
  },
}

fal-ai/minimax-music/v2.6 supports explicit lyrics and instrumental mode, but not both in the same request. ACE-Step and Stable Audio are prompt-to-audio endpoints; choose them with the model override when you want those model families. ACE-Step rejects explicit lyrics; Stable Audio rejects both lyrics and instrumental mode.

Related

Shared image tool parameters and provider selection.

Shared video tool parameters and provider selection.

Shared music tool parameters and provider selection.

Agent defaults including image, video, and music model selection.