Build with gpt-image-2

1. 1. Grab a fal API key

   Head to fal.ai/dashboard/keys, create a key, and copy it. Keys start with fal-. Treat them like passwords. You can revoke and rotate them from the same page.

2. 2. Paste it into Settings

   Open Settings, paste the key, and save. Your key lives in your browser and never leaves for a backend we control. Every render goes straight from your browser to fal.

3. 3. Send your first prompt

   Open the playground, drop in the sample below, press run. You should see an image in about three to eight seconds depending on quality.

   A 35mm film photo of a tired golden retriever
   sleeping under a kitchen table at noon.
   Soft window light, dust in the air,
   shallow depth of field, warm color grade.
   No text, no watermark.

The five-layer prompt

You can write this as one paragraph, one sentence per layer, or a loose list. The model reads all three. What matters is that every layer is present.

1. Subject. What or who is in the frame, and what they are doing.
2. Scene. Where the subject sits, and what else is visible.
3. Light. Source, direction, hardness, color temperature.
4. Style. Photograph, illustration, 3D render, poster, oil.
5. Typography and negatives. Any text on the image, and what you do not want.

A brass pocket watch lying on wet cobblestones at dusk.
Blue hour, soft rain, reflections on the stones,
35mm film photograph, shallow depth of field.
Text reading "TIMEKEEPERS" engraved on the case.
No watermark, no caption bar.

Aspect ratio choices

The model supports three canonical sizes plus auto. Pick by final use, not by taste.

Quality knob

Quality is a cost and latency dial. Use low to iterate, bump to medium once the prompt holds, and send high for the final. You will usually want to lock the seed before the final bump so the image upgrades instead of re-rolling.

Typography tips

• Put the exact text in quotes. Short strings render cleaner than paragraphs.
• Call out the font family if it matters. Sans serif, bold condensed, uppercase, hand-lettered. These reach.
• State the position. Top center, bottom third, on the product, on a sign behind the subject.
• If text is not the point, say no text, no captions, no watermarks at the end.

Realism tips

• Name a camera or film. 35mm film photograph, iPhone snapshot, medium format still life. The model picks grain and compression from the reference.
• Lock the light. Rim light from behind, overcast north window, single tungsten bulb overhead. Avoid vague words like dramatic.
• Leave room for imperfection. Dust, skin texture, slight vignetting, tiny motion blur. These are the tells that make an image read as real.

The preserve-rules pattern

Split an edit prompt into two halves. The first half is what changes. The second half is what you pin. Pinning matters because any region you do not mention is fair game for the model to rework.

Change: replace the sky with a soft pink sunset.
Preserve: the subject's face, pose, hair, clothing,
the exact position of the hands, the foreground rocks,
the camera angle, and the overall exposure on the subject.
Do not alter identity. Do not change the focal length.

Input fidelity

The edit endpoint takes an input_fidelity parameter that controls how closely the output matches the source. Three settings:

• high. Stick as close as possible. Good for logo swaps, text changes, small object insertions.
• low. Let the model restyle the frame. Good for relighting, medium changes, mood shifts.
• auto. Let the model pick based on the prompt. Safe default.

An end-to-end example

You have a product photo on a white background. You want the same bottle on wet cobblestones at dusk, same angle, same label, same glass.

Edit this product photo.
Change: place the bottle on wet cobblestones
at dusk with soft blue hour light and faint
reflections on the stones.
Preserve: the bottle's exact silhouette, the
label text and artwork, the glass color, the
specular highlights on the neck, the camera
angle, and the relative scale.
Input fidelity: high.
No new logos, no added text, no watermark.

What a good reference looks like

• Consistent palette. If your reference has five colors the output will favor those five.
• One dominant texture. Grain, halftone, oil impasto, flat gouache, glossy 3D render. Mix textures only if you know you want a collage.
• Clear lighting signature. A single specular hit or a broad soft wrap will read across generations better than a chaotic scene.
• Clean edges. Avoid references with heavy watermarks, screenshots with UI chrome, or busy collages.

Blending multiple references

You can pass more than one reference. Two is usually the sweet spot. One for palette and one for texture, or one for pose and one for light. Above three you tend to get muddy output. If you want a specific blend weight, write it into the prompt: match reference 1 for palette, reference 2 for brushwork.

Write the prompt like the reference does not exist

Counterintuitive but reliable. Describe the subject and the scene in plain language, then let the reference pull the style. The common mistake is over-describing the style in the prompt, which fights the reference and produces a blended mess.

Prompt: a small red fox drinking from a forest stream at dawn.

Reference: a moody low-key oil painting with cool shadows
and a single warm rim light.

Expected output: the fox and stream in that painterly,
low-key treatment, with the reference's color discipline
carried cleanly.

How to decide between edit and image to image

Strength semantics

Strength is how much the model is allowed to diverge from the source. Low strength hugs the input. High strength treats the input as a rough hint. A rough mental model:

• 0.2 to 0.35. Color grade, atmosphere, and small retouch work. The subject survives.
• 0.4 to 0.6. Restyle. The composition carries but the execution changes.
• 0.65 to 0.85. Re-interpretation. Only the rough layout remains.
• 0.9 and above. Near text to image. You barely see the source.

The hook-first pattern

Think of the hook as the line you would tweet. One clause. Memorable. Slightly uncomfortable or deadpan funny. The expanded prompt below it is the stage direction.

Hook:
A random photo that makes you feel pain.

Expanded:
Create an accidental smartphone photo of a bare heel
about to come down on a tiny sharp-edged plastic toy
brick on a wooden floor at night. Harsh flash, crooked
framing, realistic skin, dust on the floor, slight motion
blur, zero stylization. No blood, no injury, no text.

Plausible impossible

The strongest results sit at a specific angle of the prompt space: plausible at a glance, impossible on a second look. A CCTV still of a house cat applying to college. A waterproof disposable camera photo of a diver meeting a jellyfish the size of a van. Hold the realism knob all the way up, even when the subject is ridiculous. The mismatch is the joke.

Casual realism

Phone realism, overhead fluorescent light, slightly crooked framing, one item out of focus. These cues sell the scene more than perfect composition ever will. You are aiming for the I took this on my way to the fridge look.

Deadpan concepts

Describe the absurd as if it were a municipal notice. Flat tone, no exclamation marks, no adjectives reaching for laughs. The model will not soften the image. The tone does the work.

Negative constraints

Sometimes it is easier to tell the model what not to do. End the prompt with a short comma-separated list.

No text, no watermark, no caption bar,
no cinematic color grade, no blood,
no staged studio light.

When not to overprompt

If you can describe the picture in two sentences, do that. The model answers short prompts well. Pile on rules when the output keeps drifting. The sweet spot is usually forty to one hundred and twenty words. Above that you are fighting yourself.

Install and configure

# Node (pnpm, yarn, or npm)
pnpm add @fal-ai/client

# Python
pip install fal-client

TypeScript, text to image

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const r = await fal.subscribe("fal-ai/gpt-image-1.5", {
  input: {
    prompt:
      "A 35mm film photo of a brass pocket watch on wet cobblestones at dusk, blue hour, soft rain, no text.",
    image_size: "1024x1024",
    quality: "high",
    num_images: 1,
    output_format: "png",
    background: "auto",
  },
  logs: true,
});

console.log(r.data.images[0].url);

Python, text to image

import os
import fal_client

os.environ["FAL_KEY"] = os.environ["FAL_KEY"]

result = fal_client.subscribe(
    "fal-ai/gpt-image-1.5",
    arguments={
        "prompt": "A 35mm film photo of a brass pocket watch on wet cobblestones at dusk, blue hour, soft rain, no text.",
        "image_size": "1024x1024",
        "quality": "high",
        "num_images": 1,
        "output_format": "png",
        "background": "auto",
    },
    with_logs=True,
)

print(result["images"][0]["url"])

TypeScript, image editing

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const r = await fal.subscribe("fal-ai/gpt-image-1.5/edit", {
  input: {
    prompt:
      "Change the sky to a soft pink sunset. Preserve the subject, pose, and foreground rocks.",
    image_urls: ["https://example.com/source.png"],
    input_fidelity: "high",
    image_size: "1536x1024",
    quality: "high",
    num_images: 1,
    output_format: "png",
  },
  logs: true,
});

console.log(r.data.images[0].url);

Queue submit, for long running jobs

Use fal.queue.submit when you want to fire a job and poll for results from another process, for example from a worker or a webhook handler.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const { request_id } = await fal.queue.submit("fal-ai/gpt-image-1.5", {
  input: { prompt: "A moody low-key still life of citrus on a slate plate." },
});

const status = await fal.queue.status("fal-ai/gpt-image-1.5", {
  requestId: request_id,
  logs: true,
});

if (status.status === "COMPLETED") {
  const r = await fal.queue.result("fal-ai/gpt-image-1.5", {
    requestId: request_id,
  });
  console.log(r.data.images[0].url);
}

Text to image parameters

Edit parameters

The edit endpoint accepts everything from the text to image endpoint plus two more fields.