calesthio/generative-media-skills/black-forest-labs-flux

Produce images with Black Forest Labs FLUX

Use this evidence notation throughout your work:

• [Documented] means BFL documentation, a BFL model card/repository, BFL legal terms, or a BFL-authored paper states the fact.
• [Inference] means a conclusion follows from documented facts but BFL does not state it directly.
• [Heuristic] means production advice to validate against actual outputs.

Treat all endpoint names, limits, prices, licenses, and terms as volatile. The facts below were verified 2026-07-09. Recheck the current BFL API reference, release notes, model card, and governing license before a consequential run.

Keep the execution surfaces separate

Identify the surface before selecting parameters or stating rights.

1. BFL direct API — requests go to an official api.bfl.ai endpoint with an x-key. BFL defines the request schema, moderation, billing, asynchronous result contract, and service terms. [Documented: D1, D2, D9]
2. Third-party hosted gateway — the gateway, not BFL's direct API, defines model slugs, accepted parameters, retention, moderation, pricing, and version pinning. Never assume a BFL field or limit works unchanged. Verify that provider's current documentation and contract. [Inference]
3. Local/open-weight deployment — weights and inference run on infrastructure under the checkpoint's own license. There is no automatic BFL API moderation, retention policy, or signed-result URL. Implement filtering, provenance, storage controls, and capacity planning yourself. [Documented: D10, D11]

Do not call every downloadable FLUX checkpoint “open source.” FLUX.2 [klein] 4B is Apache-2.0; FLUX.2 [klein] 9B and FLUX.2 [dev] are downloadable/open-weight but governed by the FLUX Non-Commercial License unless a commercial weights license applies. [Documented: D10]

Select the family deliberately

Current FLUX.2 paths

Use a preview endpoint for current quality/speed only when a changing underlying snapshot is acceptable. Use a fixed endpoint for regression baselines, approvals, or compliance-sensitive reproducibility. The request contract may match while outputs change on preview. [Documented: D1, D12]

Specialized and legacy paths

• Use FLUX Erase for mask-driven removal and background reconstruction. It uses a fixed erase instruction; the caller supplies no semantic prompt. [Documented: D7]
• Use FLUX Outpainting to extend a canvas. Its current direct endpoint offers high and fast modes. [Documented: D7]
• Use FLUX.1 Fill [pro] or licensed Fill [dev] when a black/white or alpha mask must be filled with specifically prompted content. It remains a legacy path in the current API reference. [Documented: D7, D10]
• Keep FLUX.1 Kontext [pro]/[max] for an already-approved or compatibility-bound iterative edit workflow. BFL recommends FLUX.2 for new projects. The BFL paper supports Kontext's unified generation/editing and evaluates multi-turn consistency, but that does not make it the current default. [Documented: D13]
• Keep FLUX1.1 [pro]/Ultra/Raw, FLUX.1 [dev]/[schnell], Depth, Canny, and Redux only when their specific legacy behavior, adapters, or deployed assets are required. Do not silently migrate a locked workflow; run a side-by-side acceptance test. [Documented: D9, D10]

Convert the brief into a generation contract

Before prompting, record:

• final use, audience, territories, and whether the use is commercial;
• exact execution surface, endpoint/checkpoint, version strategy, and license;
• output count, size/aspect ratio, format, deadline, and cost ceiling;
• subject, action/state, environment, composition, style/medium, light, palette, and required text;
• non-negotiable identity/product/logo geometry and what may vary;
• each input image's owner, consent status, role, sensitivity, and permitted transformations;
• acceptance tests for text, color, identity, product geometry, factuality, and artifacts.

Stop if the model license, input rights, consent, or requested representation is unresolved. Do not interpret a provider accepting a request as clearance to publish it.

Prompt from visible target state

Write natural-language prompts as a clear visual description. Front-load the highest-priority content. A useful ordering is:

image type + subject + action/state + composition + environment + style/medium + lighting + palette + material/detail + required text

This is an aid, not a mandatory formula. Add only details that change visible output. FLUX.2 supports very long prompts, but BFL advises starting short and adding useful specificity. [Documented: D3]

Use positive replacement language because most FLUX paths do not expose useful negative prompting. Replace “no people” with “an empty pedestrian plaza”; replace “no blur” with “sharp focus throughout.” [Documented: D4]

For a complex automated brief, pass a JSON-shaped string as the prompt value; do not invent an undocumented top-level JSON control schema. Useful prompt-internal keys include scene, subjects, composition, camera, lighting, color_palette, style, and text. FLUX interprets the structure as language. [Documented: D1, D5]

Prompt upsampling

• On [pro]/[max], prompt upsampling is on by default; set disable_pup: true when wording must be used as written. [Documented: D2]
• On [flex], control it with prompt_upsampling. [Documented: D2]
• [klein] has no prompt upsampling. Supply the full visual direction yourself. [Documented: D4]
• [Heuristic] Disable upsampling for exact brand copy, tightly specified layouts, controlled A/B tests, and repair prompts; leave it on for broad ideation.

Direct API operating pattern

For current FLUX.2 direct endpoints:

1. POST JSON with prompt, optional input_image through input_image_8 (only through _4 on klein), dimensions, optional seed, moderation setting, format, and optional webhook fields. Use only fields documented for that endpoint. [Documented: D2]
2. Capture id, polling_url, reported cost, input megapixels, and output megapixels.
3. Poll the returned URL until Ready; handle moderated, error, and task-not-found states explicitly. Do not poll forever.
4. Download the asset immediately. BFL's signed result URL is valid for 10 minutes. Store the original response, endpoint, prompt, parameters, input hashes, output hash, and timestamps. [Documented: D5, D9]
5. Never log API keys, raw sensitive input URLs, or webhook secrets. Authenticate webhook callbacks with the configured secret.

An optional seed supports reproducibility, but do not promise identical pixels across a changing preview endpoint, different gateway, different local runtime, or changed weights. [Documented + Inference: D1, D2]

Build reference edits as explicit contracts

Single reference

State both the edit and preservation constraints:

Replace the paper label with a matte navy label in color #102A43. Keep the bottle silhouette, cap, glass reflections, camera angle, hand position, shadows, and background unchanged.

Name exact old and new text in quotation marks. For example: Replace "NORTH" with "EMBER"; retain the letter height, baseline, kerning character, embossing, and perspective. BFL explicitly recommends quoted text and precise change/preservation language. [Documented: D5]

Multiple references

Assign one role per image before writing the prompt:

Then name those roles: Use image 1 as the base scene; place the bottle from image 2 on the table; use the person from image 3 wearing the jacket from image 4; apply only the color grade and grain of image 5. BFL recommends naming “image 1,” “image 2,” and each role. [Documented: D6]

Use the fewest references that carry independent information. Resolve contradictory pose, lighting, lens, identity, or style cues before generation. On the BFL direct API, current caps are 8 for [max]/[pro]/[flex], 4 for [klein], and a recommended 6 for local [dev]. The [pro] guide also documents a 9MP total input-plus-output budget, so increasing output resolution can reduce usable reference count. [Documented: D1, D6]

[Heuristic] Build a contact sheet with input index, role, crop, provenance, and hash. Run identity/product and style references separately first; combine only after each contract works.

Control typography, color, and layout

Typography

1. Prefer [flex] when embedded text and small design details dominate; use [max] for a hard final edit when maximum consistency matters. [Documented: D1, D2]
2. Put exact copy in quotes, near the front of the prompt.
3. Specify placement, hierarchy, size class, alignment, font character, color, and substrate: Large centered headline "MOVE LIGHT" in condensed bold sans-serif, color #F7F3E8, printed flat on the upper third. [Documented: D5]
4. Keep generated strings short. Generate headline, subhead, and CTA in separate passes if needed. [Documented + Heuristic: D5]
5. Proofread at 100–200% zoom. Check every glyph, number, punctuation mark, baseline, line break, and brand spelling.
6. [Heuristic] For legal copy, pricing, long body text, or accessibility-critical text, generate the visual plate and typeset final copy deterministically in a design/compositing tool.

Color

Associate each hex code with a named object or component; do not provide an unattached palette and expect deterministic assignment. BFL documents object-bound hex steering. [Documented: D1, D5]

Example prompt fragment: Bottle body: color #0B3D2E. Cap: color #F2C94C. Wordmark "MOSS": color #FFFFFF. Background: uniform color #E9E3D5.

[Heuristic] Treat “exact color” as a steering claim, not proof of a color-managed deliverable. Sample multiple pixels in the final exported file, check color space/profile and compression, and correct in post when a brand tolerance is contractual.

Composition and sampling