create-image-gpt-image-fal
Generate a single photoreal or designed image with OpenAI gpt-image via fal.ai. Supports gpt-image-1 (default, fixed sizes — the FAL fallback for Higgsfield's `gpt_image_2`) and gpt-image-2 (`openai/gpt-image-2`, custom output sizes up to 3840px). Routes to text-to-image or the edit variant depending on whether a reference image is provided. Use for photoreal character anchors, scene keyframes, and designed sheets (e.g. storyboards) where precise layout and legible text matter.
gooseworks-ai · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gooseworks-ai/goose-skills --skill create-image-gpt-image-falAbout this skill
name: create-image-gpt-image-fal
description: Generate a single photoreal or designed image with OpenAI gpt-image via fal.ai. Supports gpt-image-1 (default, fixed sizes — the FAL fallback for Higgsfield's gpt_image_2) and gpt-image-2 (openai/gpt-image-2, custom output sizes up to 3840px). Routes to text-to-image or the edit variant depending on whether a reference image is provided. Use for photoreal character anchors, scene keyframes, and designed sheets (e.g. storyboards) where precise layout and legible text matter.
create-image-gpt-image-fal
Purpose
Generate one image via fal.ai's OpenAI gpt-image endpoints. Two model families are supported through a single --model flag:
gpt-image-1(default) —fal-ai/gpt-image-1. The FAL fallback for Higgsfield'sgpt_image_2. Fixed output sizes only. Used by:video-orchestrator/lock-characterPhase 0 (anchor portrait) and Phase 1 (angle keyframes via/edit)video-orchestrator/create-clipsPhase 1 for photoreal scenes- the orchestrator's
generate_with_fallback.pyrouter on Higgsfield failure
gpt-image-2—openai/gpt-image-2. The newer model; accepts custom output sizes (any multiple of 16, up to 3840px) and renders dense text/layouts well. Used for designed sheets such as ad storyboards (create-storyboard-sheets-fal).
The default stays gpt-image-1 so existing callers and the lock-character anchor-parity contract are unaffected. Opt into the newer model with --model gpt-image-2.
Pricing (approximate, as of 2026-05)
- gpt-image-1 — $0.04 (low), $0.08 (medium), $0.20 (high) per image. Source: fal.ai/models/fal-ai/gpt-image-1.
- gpt-image-2 — token-priced; rough per-image estimate $0.02 (low), $0.07 (medium), $0.19 (high). Source: fal.ai/models/openai/gpt-image-2.
The script defaults to medium; pass --quality high for finals.
Inputs
Required:
--prompt— text prompt. A verbatim character descriptor block goes here for character work.--output— local PNG destination.
Optional:
--model—gpt-image-1(default) orgpt-image-2.--aspect-ratio—9:16(default),16:9,1:1,2:3,3:2. gpt-image-2 also accepts3:4,4:3,4:5. Used when--image-sizeis not given.--image-size— explicitWIDTHxHEIGHT(e.g.1728x2304). gpt-image-2 only — values are rounded to multiples of 16 and capped at 3840px. Ongpt-image-1a custom size is ignored with a warning and the aspect-ratio mapping is used instead.--quality—low | medium | high(defaultmedium).--ref-image/--ref-url— a PUBLIC image URL for the/editvariant. Repeatable — pass it twice to send multiple refs (e.g. identity + style). The proxy does not upload local files, so a local path is rejected — host the image first (MCPget_upload_url→get_download_url, or any public URL) and pass that URL. When present, routes to the model's/editvariant so the model can match the references. Order matters: pass identity (character) first, then style refs.--with-logs— stream fal queue logs.
Credentials (proxy-routed — NOT a raw FAL key):
- The bundled
scripts/media_proxy.pyroutes every call through the GooseWorks fal-proxy, which bills the Ads agent. It reads~/.gooseworks/credentials.json(api_base,api_key,agent_id) — written bygooseworks login. Do not setFAL_API_KEY: an agent (cal_) token is not a FAL key and 401s against fal directly. - Set
GW_PROJECT_ID=<ad project id>in the env so the generation's spend attributes to that ad project (per-project cost shows in the app).
Preflight
test -f ~/.gooseworks/credentials.json || { echo "Missing credentials — run: gooseworks login"; exit 1; }
python3 -c "import requests" || pip3 install requests
Workflow
# Text-to-image, default model (gpt-image-1)
python3 skills/ads/capabilities/create-image-gpt-image-fal/scripts/generate.py \
--prompt "..." \
--output /path/to/anchor.png \
--aspect-ratio 9:16 \
--quality medium
# Edit-from-reference (anchor -> angle). --ref-image must be a PUBLIC URL,
# NOT a local path (the proxy does not upload local files):
python3 .../generate.py \
--prompt "..." \
--output /path/to/angle-3q-left.png \
--ref-image "https://.../anchor.png" \
--aspect-ratio 9:16
# gpt-image-2 with a custom output size (e.g. a designed storyboard sheet)
python3 .../generate.py \
--prompt "..." \
--output /path/to/storyboard.png \
--model gpt-image-2 \
--image-size 1728x2304 \
--quality high
The script:
- Loads the agent credentials from
~/.gooseworks/credentials.jsonvia the bundledmedia_proxy.py(proxy-routed; bills the Ads agent). - Resolves the model family (
--model) and output size (--image-sizeif given and supported, else the aspect-ratio mapping). - If one or more
--ref-image/--ref-urlflags are set, passes them asimage_urls=[url1, url2, ...](they must already be PUBLIC URLs) and routes to the model's/editvariant. Otherwise routes to the/text-to-imagevariant. - Submits through the GooseWorks fal-proxy and polls the queue to completion — host-swapping the
queue.fal.runstatus/response URLs to the proxy base (seemedia_proxy.py); never pollsqueue.fal.rundirectly. - Downloads the first result image to
--output. - Writes
<output>.meta.jsonwithgateway: "fal-proxy", model id,model_family, request, and cost.
Output
<output_path>— PNG (≥ 1 KB).<output_path>.meta.json— request + result metadata + cost, includingmodel_family(gpt-image-1orgpt-image-2).
Quality Checks
- Output file exists and is > 1 KB.
- For character anchors: visually inspect against the descriptor block (hair, shirt color, age).
meta.jsonincludesgateway: "fal-proxy", the resolvedmodelid,model_family,image_size, andquality.- For g