diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index c7017c329..fb2c0bfc6 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "86d897cfaa6a12b734bb8040ecd55ab2dabe749b", - "syncedAt": "2026-04-25T19:13:47.472Z" + "sha": "75d64cd4b8fb706f6a72f9c184b720cc765ba87a", + "syncedAt": "2026-04-25T19:23:48.332Z" } diff --git a/docs/cli/infer.md b/docs/cli/infer.md index dca170e04..aabcff8dc 100644 --- a/docs/cli/infer.md +++ b/docs/cli/infer.md @@ -156,9 +156,9 @@ Use `image` for generation, edit, and description. ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json openclaw infer image generate --prompt "cinematic product photo of headphones" --json -openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --openai-background transparent --prompt "simple red circle sticker on a transparent background" --json +openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json -openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --openai-background transparent --prompt "keep the logo, remove the background" --json +openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json openclaw infer image describe --file ./photo.jpg --json openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json @@ -167,10 +167,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j Notes: - Use `image edit` when starting from existing input files. -- Use `--output-format png --openai-background transparent` with - `--model openai/gpt-image-1.5` for transparent-background OpenAI PNG output. - These OpenAI-specific flags are available on both `image generate` and - `image edit`. +- Use `--output-format png --background transparent` with + `--model openai/gpt-image-1.5` for transparent-background OpenAI PNG output; + `--openai-background` remains available as an OpenAI-specific alias. Providers + that do not declare background support report the hint as an ignored override. - Use `image providers --json` to verify which bundled image providers are discoverable, configured, selected, and which generation/edit capabilities each provider exposes. diff --git a/docs/providers/fal.md b/docs/providers/fal.md index ebae2f525..8c5db1e1b 100644 --- a/docs/providers/fal.md +++ b/docs/providers/fal.md @@ -50,11 +50,16 @@ The bundled `fal` image-generation provider defaults to | Size overrides | Supported | | Aspect ratio | Supported | | Resolution | Supported | +| Output format | `png` or `jpeg` | The fal image edit endpoint does **not** support `aspectRatio` overrides. +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 diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 809e00c98..b6a0bc283 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -262,7 +262,8 @@ PNG/WebP output; the current `gpt-image-2` API rejects For a transparent-background request, agents should call `image_generate` with `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` or `"webp"`, and -`openai.background: "transparent"`. OpenClaw also protects the public OpenAI and +`background: "transparent"`; the older `openai.background` provider option is +still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth routes by rewriting default `openai/gpt-image-2` transparent requests to `gpt-image-1.5`; Azure and custom OpenAI-compatible endpoints keep their configured deployment/model names. @@ -273,13 +274,14 @@ The same setting is exposed for headless CLI runs: openclaw infer image generate \ --model openai/gpt-image-1.5 \ --output-format png \ - --openai-background transparent \ + --background transparent \ --prompt "A simple red circle sticker on a transparent background" \ --json ``` -Use the same `--output-format` and `--openai-background` flags with +Use the same `--output-format` and `--background` flags with `openclaw infer image edit` when starting from an input file. +`--openai-background` remains available as an OpenAI-specific alias. For Codex OAuth installs, keep the same `openai/gpt-image-2` ref. When an `openai-codex` OAuth profile is configured, OpenClaw resolves that stored OAuth @@ -302,7 +304,7 @@ Generate: Generate a transparent PNG: ``` -/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png openai='{"background":"transparent"}' +/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` Edit: diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md index 95a16a6e9..90a23810a 100644 --- a/docs/tools/image-generation.md +++ b/docs/tools/image-generation.md @@ -60,8 +60,10 @@ The agent calls `image_generate` automatically. No tool allow-listing needed — The same `image_generate` tool handles text-to-image and reference-image editing. Use `image` for one reference or `images` for multiple references. Provider-supported output hints such as `quality`, `outputFormat`, and -OpenAI-specific `background` are forwarded when available and reported as -ignored when a provider does not support them. +`background` are forwarded when available and reported as ignored when a +provider does not support them. Current bundled transparent-background support +is OpenAI-specific; other providers may still preserve PNG alpha if their +backend emits it. ## Supported providers @@ -126,6 +128,11 @@ Quality hint when the provider supports it. Output format hint when the provider supports it. + +Background hint when the provider supports it. Use `transparent` with +`outputFormat: "png"` or `"webp"` for transparency-capable providers. + + Number of images to generate (1–4). @@ -268,6 +275,11 @@ image model. OpenClaw routes default `gpt-image-2` transparent-background requests to `gpt-image-1.5`. `openai.outputCompression` applies to JPEG/WebP outputs. +The top-level `background` hint is provider-neutral and currently maps to the +same OpenAI `background` request field when the OpenAI provider is selected. +Providers that do not declare background support return it in `ignoredOverrides` +instead of receiving the unsupported parameter. + When asking an agent for a transparent-background OpenAI image, the expected tool call is: @@ -276,9 +288,7 @@ tool call is: "model": "openai/gpt-image-1.5", "prompt": "A simple red circle sticker on a transparent background", "outputFormat": "png", - "openai": { - "background": "transparent" - } + "background": "transparent" } ``` @@ -295,15 +305,16 @@ For headless CLI generation, use the equivalent `openclaw infer` flags: openclaw infer image generate \ --model openai/gpt-image-1.5 \ --output-format png \ - --openai-background transparent \ + --background transparent \ --prompt "A simple red circle sticker on a transparent background" \ --json ``` -The same `--output-format` and `--openai-background` flags are available on -`openclaw infer image edit`. Other bundled providers can return PNGs and may -preserve alpha when their backend emits it, but OpenClaw only exposes an -explicit transparent-background control for OpenAI image generation. +The same `--output-format` and `--background` flags are available on +`openclaw infer image edit`; `--openai-background` remains available as an +OpenAI-specific alias. Current bundled providers other than OpenAI do not +declare explicit background control, so `background: "transparent"` is reported +as ignored for them. Generate one 4K landscape image: @@ -314,7 +325,7 @@ Generate one 4K landscape image: Generate a transparent PNG: ``` -/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png openai='{"background":"transparent"}' +/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` Generate two square images: