=== AI Provider for fal.ai ===
Contributors: iamkingsleyf, kraftysprouts
Tags: ai, fal, image-generation, flux, connectors
Requires at least: 6.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.12
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Standalone fal.ai image-generation provider for the WordPress AI Client (Flux, Recraft, and related models).

== Description ==

AI Provider for fal.ai is a **standalone** WordPress plugin. It integrates [fal.ai](https://fal.ai/) with the WordPress [AI Client](https://developer.wordpress.org/reference/functions/wp_ai_client_prompt/) and [Connectors](https://make.wordpress.org/core/2026/03/18/introducing-the-connectors-api-in-wordpress-7-0/) APIs.

It is not tied to any other commercial plugin. Any theme, plugin, or custom code that uses `wp_ai_client_prompt()->generateImage()` can use fal once this provider is active and an API key is configured.

After you activate the plugin and save a fal API key under **Settings → Connectors**, image generation requests that the AI Client routes to fal run through Flux, Recraft, and related models — without each consumer embedding fal-specific HTTP code or storing API keys itself.

**Features**

* Image generation with Seedream 5.0 Pro, GPT Image 2, Nano Banana Pro/2, Flux, and Recraft V3
* Appears automatically on **Settings → Connectors** (API key authentication)
* Uses fal’s official `FAL_KEY` environment variable / PHP constant when set
* Sends the correct `Authorization: Key …` header required by fal

**Requirements**

* PHP 7.4 or higher
* WordPress 7.0 or higher (built-in AI Client), **or** WordPress 6.9 with the [php-ai-client](https://github.com/WordPress/php-ai-client) package available
* A fal.ai API key from [fal.ai Dashboard → Keys](https://fal.ai/dashboard/keys)

This plugin does **not** contact fal until another plugin or custom code requests image generation through the AI Client, or until Connectors checks provider availability.

== Installation ==

1. Upload the `ai-provider-for-fal-ai` folder to `/wp-content/plugins/`, or install the zip via **Plugins → Add New → Upload Plugin**.
2. Activate **AI Provider for fal.ai** through the **Plugins** screen.
3. Go to **Settings → Connectors**, open the fal.ai card, enter your API key, and save.
   Alternatively, define the `FAL_KEY` environment variable or PHP constant.
4. Call image generation from any AI Client consumer (core features, third-party plugins, or your own code).

== Frequently Asked Questions ==

= How do I get a fal.ai API key? =

Create an account at [fal.ai](https://fal.ai/) and generate a key under [Dashboard → Keys](https://fal.ai/dashboard/keys).

= Does this plugin store my API key? =

No. Keys are stored by WordPress **Connectors** (encrypted), or you can supply `FAL_KEY` via environment / `wp-config.php` constant. This plugin does not write its own options for credentials.

= Does this plugin work without the WordPress AI Client? =

No. On WordPress 7.0+ the AI Client is built in. On WordPress 6.9 you must have the PHP AI Client package available. Without it, the plugin loads but does not register a provider.

= Which models are available? =

Version 1.1.0 ships a static catalog including Seedream 5.0 Pro, GPT Image 2, Nano Banana Pro, Nano Banana 2, Flux Schnell/Dev/Pro/Ultra, and Recraft V3. Prefer a model with `using_model_preference()` / provider preference APIs when your consumer supports it; otherwise the AI Client selects a suitable image-capable model.

= Who can use this provider? =

Anyone. It registers with the shared WordPress AI Client registry. Themes, plugins, mu-plugins, and custom PHP that call `wp_ai_client_prompt()` can request images once fal is configured in Connectors.

= What data leaves my site? =

When image generation runs, the fal API key and the text prompt (plus generation parameters such as image size) are sent to fal.ai. See **External services**.

== External services ==

This plugin connects to the **fal.ai Model APIs** to generate images when an AI Client consumer requests it.

* **Endpoints:** `https://queue.fal.run/` (submit / status / result), `https://api.fal.ai/v1/models/requests/by-endpoint` (authenticated request-history recovery), and related fal CDN URLs for completed images. Legacy sync `https://fal.run/` is not used by this provider’s image path.
* **Data sent:** fal API key (`Authorization: Key …` header); prompt text and generation parameters supplied by the calling code.
* **When:** only when a consumer requests image generation through the AI Client or via `FalQueueClient`, or when Connectors validates that the provider is configured/available.
* **Service provider:** [fal.ai](https://fal.ai/)
* **Terms:** [https://fal.ai/legal/terms-of-service](https://fal.ai/legal/terms-of-service)
* **Privacy:** [https://fal.ai/legal/privacy-policy](https://fal.ai/legal/privacy-policy)

You are responsible for complying with fal’s terms and with applicable privacy laws for any content you send.

== Privacy ==

This plugin does not set cookies, does not track users, and does not phone home to the plugin author beyond normal plugin updates after listing on WordPress.org.

API credentials are handled by WordPress Connectors (or `FAL_KEY`). Generated image binaries are returned to the calling code (for example to sideload into the Media Library); this plugin does not persist generation history of its own.

== Changelog ==

= 1.1.12 =
* Verified WordPress 7.1 compatibility ("Tested up to" bump).
* External services section now links fal.ai's canonical legal pages (terms of service / privacy policy).

= 1.1.11 =
* Slimmed fal request-history payloads to prompt + image URL so large recoveries do not exhaust WordPress memory.

= 1.1.10 =
* Added authenticated recent-request history lookup with input/output payloads so consumers can recover orphaned completed generations automatically.
* Fixed request-ID recovery returning HTTP 405 by reading completed output from fal's durable history payload.
* Added submit/poll/fetch/history lifecycle tests.

= 1.1.9 =
* FalQueueClient::fetchByRequestId() for recovering completed queue results by model + request id.

= 1.1.8 =
* Added FalQueueClient for non-blocking fal queue submit/status/fetch (parallel batch consumers).

= 1.1.7 =
* Seedream 16:9 / landscape now requests 2048×1152 (cheap fal pixel-area tier) instead of a larger enum size.

= 1.1.6 =
* Clearer featured-image generation notice (don’t click Generate again; don’t click into the post content).
* Auto-saves the post when featured-image generation completes so the assignment is not lost if the tab closes.

= 1.1.5 =
* Added an editor guard so accidental Post→Block switches / second clicks during “Generate featured image” do not start another paid fal request.

= 1.1.4 =
* Fixed timeouts on slow models (e.g. Seedream): use fal queue submit/poll/result instead of one long fal.run request.

= 1.1.3 =
* Fixed Connectors “Connected” status showing without an API key (availability now requires a non-empty key).
* Injects FAL_KEY from the environment when Connectors does not pass a DB key.

= 1.1.2 =
* Fixed a fatal/notice when remapping the fal Connectors card: unregister the auto-discovered connector before re-registering with FAL_KEY.

= 1.1.1 =
* Fixed generated images so they include inline base64 data for WordPress AI Client consumers that do not accept remote URLs alone.

= 1.1.0 =
* Added Seedream 5.0 Pro, GPT Image 2, Nano Banana Pro, and Nano Banana 2 to the model catalog.
* Safer per-model request parameter mapping for image_size vs aspect_ratio.

= 1.0.1 =
* Plugin Check fixes: escape exception messages, ABSPATH guard on autoload, remove discouraged textdomain loader, limit readme tags, use connector registry instead of `wp_get_connector()`.

= 1.0.0 =
* Initial release.
* Registers fal.ai (`fal-ai`) with the WordPress AI Client / Connectors.
* Image generation for Flux Schnell, Flux Dev, Flux Pro, Flux Pro Ultra, and Recraft V3.
* Uses `Authorization: Key` and the official `FAL_KEY` credential name.

== Upgrade Notice ==

= 1.1.6 =
Clearer generation notice and auto-save after featured-image generation completes.

= 1.1.5 =
Prevents duplicate featured-image generation clicks (and extra fal charges) when the editor sidebar switches.

= 1.1.4 =
Uses fal’s queue API so slow image models no longer time out while fal still finishes the job.

= 1.1.3 =
Connectors no longer reports fal as Connected without an API key.

= 1.0.1 =
Plugin Check / WordPress.org compliance fixes.

= 1.0.0 =
Initial release. Activate, then add your fal API key under Settings → Connectors.