--- title: "FLUX.2 JSON Prompt Guide — Image API Newcomer Guide" description: "Beginner-friendly FLUX.2 JSON prompt guide: every field explained, 3 copy-paste examples, and when to use it vs alternatives. 3 credits on AI Content Drop." canonical: "https://aicontentdrop.com/blog/flux-2-json-prompt-guide" source: "https://aicontentdrop.com/blog/flux-2-json-prompt-guide" --- ## What This Guide Does This guide teaches you how to write a valid JSON request for **FLUX.2**, the image-generation model released by Black Forest Labs in 2025. By the end, you'll be able to send your first request to the FLUX.2 API and understand every field in the JSON — even if you've never called an AI model before. We'll cover what JSON is, what each field controls, three copy-paste prompt bodies for different creative goals, how to actually send the request (with both `curl` and JavaScript examples), and a plain-English cost breakdown so you know exactly what you're spending before you click generate. If you've already explored [prompt engineering fundamentals](https://aicontentdrop.com/blog/ai-prompt-engineering-secrets), this is where you put them into practice with a specific model and a real API surface. ## What Is FLUX.2? FLUX.2 is a family of text-to-image models built by **Black Forest Labs (BFL)**, the German AI lab founded by the original creators of the Stable Diffusion architecture. Unlike video models such as Veo or Kling, FLUX.2 generates *still images* — high-resolution photographs, product renders, character portraits, and editorial artwork — from a text description you write. The model family includes FLUX.2 Pro (the flagship cloud tier), FLUX.2 Max (highest detail), and FLUX.2-dev (the 32-billion-parameter open-weights research version). The flagship cloud model trades the raw parameter count of -dev for faster generation and a cleaner API surface — ideal for production workflows where speed and consistency matter more than maximum experimental headroom. FLUX.2 excels at photorealistic product photography, clean typography rendering, and compositional accuracy — areas where earlier open-source image models frequently struggled. What it cannot do is generate video, animate existing images, or synthesize audio. For video needs, you'd want a separate model entirely. For image generation that feeds into [video ad angles](https://aicontentdrop.com/blog/best-ai-image-models-for-video-ad-angles-2026), FLUX.2 is one of the most accurate options available in 2026. On AI Content Drop, a single FLUX.2 generation costs **3 credits** (from `IMAGE_CREDITS.flux_2 = 3` in the platform's credit table). Credits are charged only on a successful generation — if the request fails, nothing is deducted. ## The Complete JSON Prompt A **JSON request body** is a structured text message you send to an API (Application Programming Interface — a service that receives requests and returns results). JSON stands for *JavaScript Object Notation*. Despite the name, it's just a text format made of key-value pairs that any programming language can read. Here is a complete FLUX.2 request body you can copy, paste, and run right now: ``` { "prompt": "A white ceramic pour-over coffee dripper on a natural oak countertop, steam rising, morning window light, photorealistic, 4K", "width": 1024, "height": 1024, "steps": 28, "guidance": 3.5, "seed": 42, "output_format": "jpeg", "output_quality": 90, "safety_tolerance": 2 } ``` **At a glance:** `prompt` is your creative description. `width` and `height` control the output image size in pixels. `steps` controls how many refinement passes the model runs (more = slower but sharper), `guidance` controls how strictly the model follows your words versus improvising, and the remaining fields handle output format, quality, and reproducibility. ## Field-by-Field Breakdown ### prompt **Type:** string | **Required:** yes | **Max length:** ~10,000 characters (confirm in current BFL docs) This is your creative brief to the model. It tells FLUX.2 exactly what to paint. The model reads every word, so specificity wins. Aim for subject + material + lighting + mood in a single sentence. Avoid contradictory instructions like "dark but bright" — the model will average them out and produce something mediocre. - Good: "A glass perfume bottle with gold accents, soft studio lighting on a white marble surface, photorealistic" - Bad: "A bottle, nice, good lighting, pretty" ### width **Type:** integer | **Required:** no | **Default:** 1024 | **Allowed range:** 256 – 1440 (must be a multiple of 32) The horizontal pixel count of the output image. A wider value stretches the canvas left-to-right. For square social media posts, keep `width` and `height` equal. For landscape banners (e.g., YouTube thumbnails), make `width` larger. BFL recommends staying within the native training resolution range — going far above 1440 on either axis can introduce tiling artefacts. - Good: "width": 1024 for a standard square (1:1), or "width": 1344 for a landscape banner - Bad: "width": 2048 at a high steps count — slow, expensive, and prone to doubling artefacts without prompt engineering adjustments ### height **Type:** integer | **Required:** no | **Default:** 1024 | **Allowed range:** 256 – 1440 (must be a multiple of 32) The vertical pixel count. Works identically to `width` but on the vertical axis. For portrait-mode content (Instagram Stories, TikTok covers), set `height` larger than `width`. - Good: "height": 1344, "width": 768 for a 9:16 portrait crop suitable for Stories or Reels covers - Bad: "height": 100 — too small for any commercial use; the output will look blurry when scaled up ### steps **Type:** integer | **Required:** no | **Default:** 28 | **Allowed range:** 1 – 50 *Steps* is the number of denoising iterations the model runs on the image. Think of it like the number of brushstrokes an artist takes to finish a painting. More steps = more refined detail, but also slower generation time and a slightly higher cost per call on metered plans. For most production work, 28 is the sweet spot. Drop to 20 for fast prototyping, or go up to 40 if you need to extract every bit of texture detail. - Good: "steps": 28 — balanced speed and quality for ad-ready product images - Bad: "steps": 4 for a final hero image — output will look undercooked with visible noise ### guidance **Type:** float (number with decimals) | **Required:** no | **Default:** 3.5 | **Allowed range:** 1.5 – 5.0 (confirm exact bounds in current BFL docs) *Guidance scale* controls the trade-off between prompt adherence and creative freedom. A low value (1.5–2.5) gives the model more latitude to improvise — useful when your prompt is intentionally vague. A high value (4.0–5.0) forces the model to hew closely to every word you wrote — useful for precise product descriptions. At 3.5, FLUX.2 follows your prompt well while retaining some visual coherence. - Good: "guidance": 4.0 when your prompt names a specific material, color, or brand style you need exactly - Bad: "guidance": 5.0 with a vague prompt — the model over-interprets sparse words and produces inconsistent results ### seed **Type:** integer | **Required:** no | **Default:** random (a new value each run) A *seed* is a number that initializes the random starting point for the generation. If you use the same seed and the same prompt, you get a reproducible output — the image will look nearly identical on every run. This is useful when you find a great result and want to make small prompt tweaks while keeping the core composition stable. Omit the seed (or set it to `null`) for fully random outputs on each run. - Good: "seed": 42 when you've found a composition you like and want to iterate on the lighting description - Bad: using the same seed with a wildly different prompt — the seed guides initialization, but a completely different subject will still produce a completely different image ### output_format **Type:** string (enum) | **Required:** no | **Default:** `"jpeg"` | **Allowed values:** `"jpeg"`, `"png"`, `"webp"` The file format for your output image. JPEG is smaller and loads faster on web pages. PNG preserves a transparent background (alpha channel) if your prompt produces one. WebP is a modern format that matches JPEG quality at about 25% smaller file size — good for landing pages where load speed matters. - Good: "output_format": "webp" for a product image going directly onto a web page - Bad: "output_format": "png" for a hero lifestyle shot where you don't need transparency — PNG files will be 3–5× larger for no quality benefit ### output_quality **Type:** integer | **Required:** no | **Default:** 80 | **Allowed range:** 1 – 100 (applies to JPEG and WebP; ignored for PNG which is lossless) Controls the compression level for lossy formats. Higher values preserve more image detail at the cost of larger file size. For final ad creatives you'll upload to Meta or Google, use 90+. For quick iteration previews, 70–80 is fine. - Good: "output_quality": 90 for the production version you submit to an ad platform - Bad: "output_quality": 40 on a final asset — noticeable JPEG compression blocks will be visible in the output, especially in solid-color brand backgrounds ### safety_tolerance **Type:** integer | **Required:** no | **Default:** 2 | **Allowed range:** 1 – 6 (1 = strictest, 6 = most permissive) Controls how strictly BFL's content-safety filter interprets your prompt. At the default of 2, the filter blocks clearly harmful requests while allowing realistic portraiture, commercial product photography, and fashion imagery. If your legitimate prompt is being rejected (for example, a medical-device product shot being flagged as graphic), try raising this to 3. You cannot set it above your account's allowed maximum. - Good: "safety_tolerance": 2 for standard e-commerce and lifestyle images — covers 95% of commercial use cases - Bad: setting this to 6 by default — if a prompt accidentally triggers a policy, the flag gives BFL no room to intervene ## Allowed Values Reference Table Use this table as a quick reference when you're building a prompt and need to know what's legal for each field. | Field | Type | Min | Max / Options | Recommended Default | | --- | --- | --- | --- | --- | | prompt | string | 1 char | ~10,000 chars | — | | width | integer | 256 | 1440 (multiples of 32) | 1024 | | height | integer | 256 | 1440 (multiples of 32) | 1024 | | steps | integer | 1 | 50 | 28 | | guidance | float | 1.5 | 5.0 | 3.5 | | seed | integer / null | 0 | 4,294,967,295 (2³²−1) | omit (random) | | output_format | enum | — | "jpeg" | "png" | "webp" | "jpeg" | | output_quality | integer | 1 | 100 | 80 | | safety_tolerance | integer | 1 | 6 | 2 | | aspect_ratio | string (alt. to w/h) | — | "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "21:9" | "1:1" | Note on `aspect_ratio`: the BFL API accepts either an `aspect_ratio` shorthand *or* explicit `width` + `height` integers — not both at the same time. Use `aspect_ratio` when you want the model to pick the best pixel resolution automatically; use explicit dimensions when you need a specific pixel count (e.g., exactly 1344×768 for a YouTube thumbnail). ## 3 Working Copy-Paste Examples ### Example 1 — E-Commerce Product Shot ``` { "prompt": "A pair of white minimalist running shoes on a polished concrete pedestal, soft rim lighting, neutral grey background, commercial product photography, photorealistic, 8K detail", "width": 1024, "height": 1024, "steps": 32, "guidance": 4.0, "seed": 1001, "output_format": "webp", "output_quality": 92, "safety_tolerance": 2 } ``` A higher `guidance` of 4.0 is deliberate here — you want the model to reproduce the exact product surface and lighting setup you described, not improvise. The seed is fixed at 1001 so you can re-run this prompt with small text changes (swap "white" for "black") and compare results side by side without the composition shifting underneath you. WebP output keeps the image file light for fast-loading product pages. Expect a clean, studio-style hero shot ready for Meta or Google Shopping ads. ### Example 2 — Portrait / Founder Character ``` { "prompt": "A confident South Asian woman founder in her 30s, wearing a tailored charcoal blazer, direct eye contact with camera, shallow depth of field, warm office bokeh background, natural window light, editorial portrait photography", "width": 832, "height": 1216, "steps": 30, "guidance": 3.5, "seed": 2077, "output_format": "jpeg", "output_quality": 88, "safety_tolerance": 2 } ``` Portrait orientation (832×1216) gives you a natural 2:3 crop that works for LinkedIn banners, Instagram portrait posts, and UGC-style ad creatives. A guidance of 3.5 lets FLUX.2 interpret "shallow depth of field" and "warm bokeh" with some creative latitude, which tends to produce more natural-looking background separation than forcing guidance higher. The seed is set so you can iterate on the blazer color or background setting without losing the face composition. ### Example 3 — Cinematic Scene ``` { "prompt": "A rain-slicked Tokyo alley at dusk, neon kanji signage reflected in puddles, lone figure in a dark trench coat walking away from camera, cinematic anamorphic lens flare, moody blue-orange color grade, film grain", "width": 1344, "height": 768, "steps": 35, "guidance": 3.2, "output_format": "jpeg", "output_quality": 90, "safety_tolerance": 2 } ``` Landscape orientation (1344×768) matches the cinematic 16:9 aspect ratio — exactly right for YouTube thumbnails, pre-roll ad frames, or video storyboard reference images. A slightly lower guidance of 3.2 gives FLUX.2 room to interpret "film grain" and "anamorphic lens flare" artistically rather than literally. No seed is set here because you want every run to explore a slightly different atmospheric interpretation — useful when generating multiple scene variants for A/B testing. ## How to Send the Request An **API endpoint** is a URL address where a server listens for requests. When you POST a JSON body to an endpoint, the server reads your fields, runs the model, and sends back a response. For FLUX.2, the official endpoint from Black Forest Labs lives at `https://api.bfl.ai/v1/flux-pro-1.1` (the standard FLUX.2 Pro tier). Authentication uses an API key you pass in an HTTP header named `X-Key`. You get this key from your BFL dashboard at [api.bfl.ai](https://api.bfl.ai). **Using curl** (a command-line tool available on Mac, Linux, and Windows 11 by default — open your terminal and paste this): ``` curl -X POST "https://api.bfl.ai/v1/flux-pro-1.1" \ -H "Content-Type: application/json" \ -H "X-Key: YOUR_BFL_API_KEY" \ -d '{ "prompt": "A white ceramic pour-over coffee dripper on a natural oak countertop, steam rising, morning window light, photorealistic, 4K", "width": 1024, "height": 1024, "steps": 28, "guidance": 3.5, "seed": 42, "output_format": "jpeg", "output_quality": 90, "safety_tolerance": 2 }' ``` **Using JavaScript** (`fetch` — works in any modern browser or Node.js environment): ``` const response = await fetch("https://api.bfl.ai/v1/flux-pro-1.1", { method: "POST", headers: { "Content-Type": "application/json", "X-Key": "YOUR_BFL_API_KEY" }, body: JSON.stringify({ prompt: "A white ceramic pour-over coffee dripper on a natural oak countertop, steam rising, morning window light, photorealistic, 4K", width: 1024, height: 1024, steps: 28, guidance: 3.5, seed: 42, output_format: "jpeg", output_quality: 90, safety_tolerance: 2 }) }); const data = await response.json(); console.log(data); // { id: "...", status: "...", result: { ... } } ``` Or skip the API key entirely. Paste the prompt directly into [AI Content Drop's chat](https://aicontentdrop.com/) or go to [/generate/images](https://aicontentdrop.com/best-ai-video-generator) and select FLUX.2 from the model picker. We handle the request on your behalf — no API key, no terminal, no code required. ## What the Response Looks Like FLUX.2 via the BFL API is **asynchronous**. That means when you POST your JSON, the server does not immediately hand back the finished image. Instead it returns a task ID and a status, and you poll a separate endpoint until generation is complete. A typical initial response looks like this: ``` { "id": "4f3a2b1c-8e9d-4c7b-a1f0-1234567890ab", "status": "Pending" } ``` `id` is the *task ID* — a unique string that identifies your generation job on BFL's servers. `status` starts as `"Pending"` and moves through `"Processing"` to `"Ready"` when done. To check progress, GET `https://api.bfl.ai/v1/get_result?id=YOUR_TASK_ID`. A completed response looks like: ``` { "id": "4f3a2b1c-8e9d-4c7b-a1f0-1234567890ab", "status": "Ready", "result": { "sample": "https://cdn.bfl.ai/results/4f3a2b1c.jpeg" } } ``` `result.sample` is the URL where your finished image is hosted. Typical generation time for FLUX.2 Pro at 28 steps is 8–20 seconds, so polling once every 3 seconds is reasonable. Fetch the image URL with a GET request to download or display it. ## Common Errors and Fixes - **`401 Unauthorized` — "Invalid API key"** Your `X-Key` header is missing, empty, or contains a typo. Log into [api.bfl.ai](https://api.bfl.ai), copy your key fresh, and paste it again — avoid trailing spaces. - **`422 Unprocessable Entity` — invalid field value** One of your numeric fields is out of range (e.g., `steps: 200` or `width: 100`). Cross-check every value against the reference table above. - **`400 Bad Request` — "prompt is required"** The `prompt` key is missing or spelled incorrectly (JSON is case-sensitive — `Prompt` is not the same as `prompt`). Check your JSON for typos. - **Status `"Content Moderated"` — your prompt was rejected** The safety filter caught something in your prompt. Remove words that imply violence, explicit content, or real named individuals. If you're generating a legitimate product image being falsely flagged, try raising `safety_tolerance` from 2 to 3 and rewording the prompt. - **`429 Too Many Requests` — quota exceeded** You've hit BFL's rate limit on your API tier. Wait 60 seconds and retry, or upgrade your BFL plan. On AI Content Drop, credit-based access is separate from BFL's rate limits — the platform manages queuing for you. - **`width` or `height` not a multiple of 32** FLUX.2 requires pixel dimensions to align to a 32-pixel grid. Allowed values: 256, 288, 320, 352, 384 … 1408, 1440. Round your target size up to the nearest multiple of 32. - **Image returns but looks wrong — subject doubled or fragmented at large sizes** You've likely used a very high resolution (close to 1440 on both axes) with a prompt that describes a single centered subject. Drop either `width` or `height` to create an asymmetric canvas, or add "single object, centered composition" to the prompt to help the model understand the layout. ## FLUX.2 vs Alternatives — When to Use This AI Content Drop gives you access to multiple image models via the [marketplace](https://aicontentdrop.com/marketplace). Here is a quick three-way decision table: | Scenario | Best Choice | | --- | --- | | **Use FLUX.2 if** you need photorealistic product renders, clean typography in the image, or you want to batch multiple variations cheaply (3 credits per image). FLUX.2's compositional accuracy and low credit cost make it ideal for e-commerce image-to-ad pipelines where you generate 10–20 variants at a time. Also the right pick if you want to explore [self-hosted vs cloud tradeoffs](https://aicontentdrop.com/blog/self-hosted-vs-cloud-ai) — FLUX.2-dev (32B) is available on AI Content Drop's unlimited annual tier (Ultra and Enterprise Max annual) at zero credit cost. | **FLUX.2** (3 credits) | | **Use Grok Imagine if** you need images generated from a text conversation in the chat interface, or you want a tightly integrated generate-then-describe loop without switching pages. Grok Imagine costs 11 credits per image but excels at following complex multi-sentence creative briefs that reference cultural or current events. | **Grok Imagine** (11 credits) | | **Use Nano Banana Pro if** you need 4K-resolution marketing hero images with rich skin tones and lighting nuance — avatar photography for UGC or brand shoots. It costs 10 credits and trades FLUX.2's typography accuracy for superior photorealistic human rendering. | **Nano Banana Pro** (10 credits) | ## Cost Math for Newcomers FLUX.2 costs **3 credits** per successful generation on AI Content Drop. Credits are charged post-deduction — meaning if your request fails for any reason (content policy, API error, timeout), nothing is deducted from your balance. A real example: suppose you're building 10 product angle variants for a new sneaker launch — one image per colorway and lighting setup. That's **10 × 3 = 30 credits**. On the Starter plan ($19/month, 150 credits), 30 credits represents 20% of your monthly budget. If you also generate a few rounds of iteration (say 20 more images to narrow down the best composition), you're looking at 90 credits total — still within a single month on the Starter plan. Compare that to using a model like Grok Imagine at 11 credits per image: the same 30-image batch would cost 330 credits, pushing you past the Starter plan's entire monthly allowance. For high-volume image generation, FLUX.2 at 3 credits is one of the most cost-efficient high-quality options on the platform. On the **Ultra or Enterprise Max annual plan**, FLUX.2-dev (the 32B self-hosted version) is available at zero credit cost through AI Content Drop's unlimited tier. This is the best option for studios running hundreds of image generations per week. ## Glossary **Prompt** The text description you send to the model telling it what to generate. In FLUX.2, this is the `prompt` field in your JSON body. **JSON (JavaScript Object Notation)** A plain-text format for sending structured data. It uses curly braces `{}`, key-value pairs like `"steps": 28`, and commas between fields. **API Request** A message you send to a server asking it to do something — in this case, generate an image. The request contains your JSON body and authentication headers. **Endpoint** The specific URL address where the API listens for requests. For FLUX.2 Pro, this is `https://api.bfl.ai/v1/flux-pro-1.1`. **Task ID** A unique identifier the server returns immediately after you submit a generation request. You use this ID to poll for the result. **Polling** Repeatedly asking the server "is it done yet?" by making GET requests to the results endpoint with your task ID, until the status changes from "Pending" to "Ready". **Guidance Scale** A number that controls how strictly the model follows your prompt. Higher values = stricter adherence to your words; lower values = more creative interpretation. **Seed** An integer that initializes the randomness in the generation process. The same seed + the same prompt reliably produces very similar outputs, enabling reproducibility. ## FAQ ### Can I just use the chat instead of writing JSON? Yes. Head to [/chat](https://aicontentdrop.com/) and describe what you want in plain English. The platform's chat system will route your message to FLUX.2 (or another image model, depending on your description) and return the generated image directly in the conversation. No JSON, no API key, no code needed. ### What if I get a 401 error? A 401 means the server rejected your API key. Your `X-Key` header is either missing, expired, or contains a copy-paste error (watch out for leading/trailing spaces). Log into your BFL account, regenerate the key, and paste it fresh. ### What if I need an aspect ratio that's not in the list? You can't request an arbitrary ratio like 7:3 — pick the closest supported option and crop the image afterward in any image editor. For example, to get a 5:4 crop, generate at 16:9 (1280×720) and then trim the sides in Figma, Canva, or Photoshop. ### Does FLUX.2 support negative prompts? FLUX.2 Pro and FLUX.2 Max do not expose a separate `negative_prompt` field in the current BFL API — the model handles avoidance through its internal training rather than through an explicit exclusion list. If you need to push the model away from something (e.g., avoid blurry backgrounds), phrase it as a positive instruction instead: "crisp in-focus background, sharp everywhere" tends to work better than trying to negate an unwanted property. Confirm the latest API surface at [docs.bfl.ai](https://docs.bfl.ai).