# Fal AI Image

> Use fal.ai for text-to-image and image-edit generation, model comparison, queue-based image workflows, and cost-aware experiment tracking with Nano Banana and GPT Image endpoints.

- Skill: `gabrielmoreira/fal-ai-image` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/fal-ai-image`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/fal-ai-image/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/fal-ai-image

---


# fal.ai Image

Use this skill when the user wants to generate or edit images through `fal.ai`, compare multiple marketplace image models, or build repeatable experiment workflows with prompts, references, outputs, and costs tracked in a consistent way.

## Philosophy: Standardize The Harness, Not The Image Model

fal gives one platform surface for many image models, but the useful controls still differ by model family. The right abstraction is:

- standardize auth, queueing, file handling, output capture, and cost tracking
- keep model-specific knobs explicit
- compare models on the same task, not by pretending they all expose the same schema

**Before generating, ask:**
- Is this a fresh generation or an edit run?
- What must stay constant across models: prompt intent, reference images, size target, transparency, or output count?
- Which model-specific controls materially affect fairness and need to be frozen?
- Do we need pre-run cost estimates, per-run request IDs, or both?

**Core principles**:
1. **Queue-first for tracked experiments**: image calls can be synchronous, but queue mode gives request IDs, polling, and consistent logging.
2. **Reference discipline matters**: editing runs should pass only the images the model actually needs; too many references dilute control.
3. **Prompt parity beats fake parity**: keep the task stable, then document the real model-specific compromises.
4. **Tracking is part of the run**: a generation is not complete until prompt, request metadata, outputs, and cost signals are recorded.

## What This Skill Provides

- A portable, repo-scoped fal image workflow with no repo-wide Python packaging requirement.
- A generic queue-based image runner for both text-to-image and edit endpoints.
- Model presets for:
  - `grok-imagine-image-t2i`
  - `grok-imagine-image-edit`
  - `nano-banana-2-t2i`
  - `nano-banana-2-edit`
  - `nano-banana-pro-t2i`
  - `nano-banana-pro-edit`
  - `gpt-image-1.5-t2i`
  - `gpt-image-1.5-edit`
- Platform tooling for:
  - model lookup
  - pricing
  - estimate-cost
  - usage
  - request audit
- A batch runner that executes the same image task across multiple fal models and appends a central ledger row per run.

## Working With fal Images In This Repo

### Core Execution Pattern

For tracked image jobs, this skill uses fal's queue API:

- submit: `POST https://queue.fal.run/{endpoint_id}`
- status: `GET https://queue.fal.run/{endpoint_id}/requests/{request_id}/status`
- result: `GET https://queue.fal.run/{endpoint_id}/requests/{request_id}`

Authentication uses:

- `Authorization: Key $FAL_KEY`

Important platform headers for repeatable comparison runs:

- `X-Fal-Store-IO: 1`
- `x-app-fal-disable-fallback: true`

The runner also captures response headers such as:

- `x-fal-request-id`
- `x-fal-billable-units`

### Why This Skill Uses Queue HTTP

The official `fal-client` SDK is valid and supported, but this repo's main requirement is portability inside a Codex skill. The raw queue endpoints are documented and stable enough for a deterministic wrapper, so the scripts in this skill stay on Python stdlib and can still be invoked with `uv run`.

### Prompting Guidance For Image Comparison

Prompt like art direction, not like marketing copy:

- subject identity
- composition
- camera/framing
- background
- rendering style
- edit constraints
- exclusions

For edit comparisons:

- explicitly say what must stay unchanged
- keep the edit localized in language even if the model edits holistically
- keep reference count low
- be specific about transparency or background removal if needed

Background handling matters more than the prompt wording suggests:

- `gpt-image-1.5` is the safest option here when you genuinely need transparent output.
- `nano-banana-2` and `nano-banana-pro` should be treated as chroma-key models for this workflow, not transparent-background models.
- In this repo's experiments, Grok behaved more like the Banana models than GPT for background handling, so prefer chroma there too unless a later run proves otherwise.
- For chroma-key runs, ask for an exact flat green background: `#00FF00`, with no gradients, no cast shadows on the background, no texture, and no green spill on the subject.
- Do not use magenta by default for this pirate workflow. `#FF00FF` sits too close to the warm red/purple bandana family and is more likely to contaminate edge colors.

For text-to-image comparisons:

- hold composition intent stable
- ask for one clear deliverable
- keep size/background expectations explicit

Do not overload first comparison runs with long prompt stacks. The first job is to test prompt adherence, identity preservation, and edit usefulness.

## Scripts

- `scripts/fal_queue_image_run.py`
  - one text-to-image or image-edit queue run
  - writes request/result JSON
  - downloads image outputs
  - writes normalized run manifest
- `scripts/fal_platform_models.py`
  - query fal platform APIs for model metadata and cost surfaces
- `scripts/fal_image_experiment_matrix.py`
  - run the same task across multiple image presets
  - append central ledger rows

## Repo Workflow

Machine-readable tracking:

- `experiments/fal-image/ledger.jsonl`
- `experiments/fal-image/ledger.csv`
- `experiments/fal-image/<timestamp>-<slug>/batch.json`

Human-readable tracking:

- `prompts/<timestamp>-...-prompts.md`
- `learnings/<timestamp>-...-learnings.md`

Generated images should still live under the appropriate `public/assets/.../concepts/...` path for the asset family being tested.

## Anti-Patterns To Avoid

❌ **Anti-pattern: flattening all image models into one fake prompt schema**
Why bad: you hide the controls that actually affect quality and cost.
Better: use shared runner behavior plus explicit per-model presets and overrides.

❌ **Anti-pattern: treating edit and generate as the same task**
Why bad: edit runs depend on reference discipline and preservation constraints that text-to-image runs do not.
Better: keep separate presets and separate experiment configs for generation and editing.

❌ **Anti-pattern: recording only prompts and final PNGs**
Why bad: you cannot audit request IDs, retries, or cost later.
Better: always save raw JSON, normalized manifests, and ledger rows.

❌ **Anti-pattern: comparing models with hidden fallback routing**
Why bad: you may think you tested one endpoint but actually hit another route.
Better: set `x-app-fal-disable-fallback: true` on strict comparison runs.

❌ **Anti-pattern: stuffing many reference images into every edit**
Why bad: it weakens edit control and makes failure analysis harder.
Better: pass only the minimum reference images the edit actually needs.

❌ **Anti-pattern: asking Banana-family models for transparency and trusting the result**
Why bad: you may get a faux-transparent dark backdrop instead of a clean extraction surface.
Better: use an explicit chroma-key background and key it out later.

## References

- Platform notes: `references/fal-platform-notes.md`
- Queue and inference notes: `references/fal-queue-and-inference.md`
- Image model notes: `references/fal-image-models.md`
- Model presets: `assets/model-presets.json`

## Remember

A good fal image workflow is not just "can it render." It is:

- reproducible
- comparable
- cost-visible
- honest about model differences