mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-16 16:41:41 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
268 lines
10 KiB
Markdown
268 lines
10 KiB
Markdown
---
|
|
summary: "fal image, video, and music generation setup in OpenClaw"
|
|
title: "Fal"
|
|
read_when:
|
|
- You want to use fal image generation in OpenClaw
|
|
- You need the FAL_KEY auth flow
|
|
- You want fal defaults for image_generate, video_generate, or music_generate
|
|
---
|
|
|
|
OpenClaw ships a bundled `fal` provider for hosted image, video, and music
|
|
generation.
|
|
|
|
| Property | Value |
|
|
| -------- | ------------------------------------------------------------------------------- |
|
|
| Provider | `fal` |
|
|
| Auth | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) |
|
|
| API | fal model endpoints (`https://fal.run`; video jobs use `https://queue.fal.run`) |
|
|
| Base URL | Override with `models.providers.fal.baseUrl` |
|
|
|
|
## Getting started
|
|
|
|
<Steps>
|
|
<Step title="Set the API key">
|
|
```bash
|
|
openclaw 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.
|
|
|
|
</Step>
|
|
<Step title="Set a default image model">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
imageGenerationModel: {
|
|
primary: "fal/fal-ai/flux/dev",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Image generation
|
|
|
|
The bundled `fal` image-generation provider defaults to
|
|
`fal/fal-ai/flux/dev`.
|
|
|
|
| Capability | Value |
|
|
| -------------- | ------------------------------------------------------------------ |
|
|
| Max images | 4 per request; Krea 2: 1 per request |
|
|
| Size overrides | `1024x1024`, `1024x1536`, `1536x1024`, `1024x1792`, `1792x1024` |
|
|
| Aspect ratio | Supported everywhere except Flux image-to-image |
|
|
| Resolution | `1K`, `2K`, `4K` (per-model limits below) |
|
|
| Output format | `png` (default) or `jpeg`; Krea 2 rejects `outputFormat` overrides |
|
|
|
|
Edit requests (reference images via the shared `image` / `images` parameters)
|
|
route to a per-model edit endpoint with per-model reference limits:
|
|
|
|
| Model family | Model ref after `fal/` | Edit endpoint | Max reference images |
|
|
| ------------------------- | -------------------------------------- | ----------------- | -------------------- |
|
|
| Flux and other fal models | `fal-ai/flux/dev` (default) | `/image-to-image` | 1 |
|
|
| GPT Image | `openai/gpt-image-*` | `/edit` | 10 |
|
|
| Grok Imagine | `xai/grok-imagine-image` | `/edit` | 3 |
|
|
| Nano Banana (legacy) | `fal-ai/nano-banana` | `/edit` | 3 |
|
|
| Nano Banana 2 | `fal-ai/nano-banana-*` | `/edit` | 14 |
|
|
| Nano Banana 2 Lite | `google/nano-banana-2-lite` | `/edit` | 14 |
|
|
| Krea 2 | `krea/v2/{medium,large}/text-to-image` | none (style refs) | 10 style references |
|
|
|
|
<Warning>
|
|
Flux image-to-image requests do **not** support `aspectRatio` overrides. GPT
|
|
Image and Nano Banana 2 edit requests use fal's `/edit` endpoint and accept
|
|
aspect-ratio hints. Nano Banana 2 also accepts extra-native wide/tall ratios
|
|
such as `4:1`, `1:4`, `8:1`, and `1:8`; Krea 2 validates its own smaller
|
|
aspect-ratio subset. Grok Imagine has its own ratio list (including `2:1`,
|
|
`20:9`, `19.5:9`, and their inverses) and only accepts `1K`/`2K` resolutions;
|
|
legacy Nano Banana and Nano Banana 2 Lite reject `resolution` overrides.
|
|
</Warning>
|
|
|
|
Krea 2 models use fal's native Krea payload schema. OpenClaw 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`; OpenClaw 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`. fal does not declare an explicit transparent-background
|
|
control in OpenClaw, so `background: "transparent"` is reported as an ignored
|
|
override for fal models.
|
|
Krea 2 endpoints do not expose an `output_format` request field through fal, so
|
|
OpenClaw rejects `outputFormat` overrides for Krea requests.
|
|
|
|
To use Krea 2 Medium:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
imageGenerationModel: {
|
|
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`.
|
|
|
|
| Capability | Value |
|
|
| ---------- | ------------------------------------------------------------------ |
|
|
| Modes | Text-to-video, single-image reference, Seedance reference-to-video |
|
|
| Runtime | Queue-backed submit/status/result flow for long-running jobs |
|
|
| Timeout | 20 minutes per job by default; status polled every 5 seconds |
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Available video models">
|
|
**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.
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="Seedance 2.0 config example">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
videoGenerationModel: {
|
|
primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Seedance 2.0 reference-to-video config example">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
videoGenerationModel: {
|
|
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.
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="HeyGen video-agent config example">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
videoGenerationModel: {
|
|
primary: "fal/fal-ai/heygen/v2/video-agent",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Music generation
|
|
|
|
The bundled `fal` plugin also registers a music-generation provider for the
|
|
shared `music_generate` tool.
|
|
|
|
| Capability | Value |
|
|
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
| Default model | `fal/fal-ai/minimax-music/v2.6` |
|
|
| Models | `fal-ai/minimax-music/v2.6` (mp3), `fal-ai/ace-step/prompt-to-audio` (wav), `fal-ai/stable-audio-25/text-to-audio` (wav) |
|
|
| Max duration | 240 seconds |
|
|
| Runtime | Synchronous request plus generated audio download |
|
|
|
|
Use fal as the default music provider:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
musicGenerationModel: {
|
|
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.
|
|
|
|
<Tip>
|
|
The tables and accordions above cover the model families the bundled fal
|
|
provider special-cases. Other fal image endpoint ids can still be selected as
|
|
the image model; they are treated like Flux (generic `image_size` payload, one
|
|
reference image via `/image-to-image`).
|
|
</Tip>
|
|
|
|
## Related
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Image generation" href="/tools/image-generation" icon="image">
|
|
Shared image tool parameters and provider selection.
|
|
</Card>
|
|
<Card title="Video generation" href="/tools/video-generation" icon="video">
|
|
Shared video tool parameters and provider selection.
|
|
</Card>
|
|
<Card title="Music generation" href="/tools/music-generation" icon="music">
|
|
Shared music tool parameters and provider selection.
|
|
</Card>
|
|
<Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
|
|
Agent defaults including image, video, and music model selection.
|
|
</Card>
|
|
</CardGroup>
|