mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-20 19:34:45 +00:00
66b4306a2a
Fix Fal image-edit routing for GPT Image 2 and Nano Banana 2, including multi-image edit payloads and provider-specific reference limits. - Routes GPT Image 2/Nano Banana 2 edits through Fal `/edit` endpoints with `image_urls`. - Keeps Flux/custom image-to-image edits on singular `image_url` and preserves exact custom `/edit` paths. - Documents and tests provider caps: Flux/custom 1, GPT Image 2 10, Nano Banana 2 14. Verified with focused Fal provider tests, oxlint, oxfmt, `git diff --check`, docs listing, green PR CI, and live Fal calls for GPT Image 2, Nano Banana 2, Flux, plus the GPT Image 2 10-ref cap edge. Co-authored-by: Leo Ge <116452300+leoge007@users.noreply.github.com>
172 lines
5.0 KiB
Markdown
172 lines
5.0 KiB
Markdown
---
|
|
summary: "fal image and video 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 or video_generate
|
|
---
|
|
|
|
OpenClaw ships a bundled `fal` provider for hosted image and video generation.
|
|
|
|
| Property | Value |
|
|
| -------- | ------------------------------------------------------------- |
|
|
| Provider | `fal` |
|
|
| Auth | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) |
|
|
| API | fal model endpoints |
|
|
|
|
## Getting started
|
|
|
|
<Steps>
|
|
<Step title="Set the API key">
|
|
```bash
|
|
openclaw onboard --auth-choice fal-api-key
|
|
```
|
|
</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 |
|
|
| Edit mode | Flux: 1 reference image; GPT Image 2: 10; Nano Banana 2: 14 |
|
|
| Size overrides | Supported |
|
|
| Aspect ratio | Supported for generate and GPT Image 2/Nano Banana 2 edit |
|
|
| Resolution | Supported |
|
|
| Output format | `png` or `jpeg` |
|
|
|
|
<Warning>
|
|
Flux image-to-image requests do **not** support `aspectRatio` overrides. GPT
|
|
Image 2 and Nano Banana 2 edit requests use fal's `/edit` endpoint and accept
|
|
aspect-ratio hints.
|
|
</Warning>
|
|
|
|
Use `outputFormat: "png"` when you want PNG output. fal does not declare an
|
|
explicit transparent-background control in OpenClaw, so `background:
|
|
"transparent"` is reported as an ignored override for fal models.
|
|
|
|
To use fal as the default image provider:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
imageGenerationModel: {
|
|
primary: "fal/fal-ai/flux/dev",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## 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 |
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Available video models">
|
|
**HeyGen video-agent:**
|
|
|
|
- `fal/fal-ai/heygen/v2/video-agent`
|
|
|
|
**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`
|
|
|
|
</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.
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="HeyGen video-agent config example">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
videoGenerationModel: {
|
|
primary: "fal/fal-ai/heygen/v2/video-agent",
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
<Tip>
|
|
Use `openclaw models list --provider fal` to see the full list of available fal
|
|
models, including any recently added entries.
|
|
</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="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
|
|
Agent defaults including image and video model selection.
|
|
</Card>
|
|
</CardGroup>
|