FLUX Image Generation & Editing

Black Forest Labs FLUX model family — from sub-second FLUX.2 [klein] to 4MP flagship [max], covering text-to-image, multi-reference editing, typography, and exact hex color control. OpenAI-compatible drop-in.

Overview

FLUX is the flagship image generation model family from Black Forest Labs (BFL), based in Germany. The latest FLUX.2 generation spans 5 tiers from sub-second to 4MP flagship quality, alongside the previous-generation FLUX.1 Kontext for image editing — 7 active models in total. Legacy FLUX.1 [pro] models also remain callable. The APIYI gateway wraps BFL’s async polling API into a synchronous OpenAI Images API (/v1/images/generations and /v1/images/edits), so you can drop in the OpenAI SDK with just a base_url change.

🎨 Key Highlights: FLUX.2 [max] uniquely supports grounding search for real-time web knowledge. Native 4MP output (2048×2048) + up to 8 multi-reference images + 32K-token prompts + precise hex color control + best-in-class typography. Ideal for flagship quality, multi-image consistency, brand color fidelity, and professional layouts in production.

All image APIs are synchronous — there is no task ID to poll, and if your client disconnects the result is lost while the request is still billed. Set a generous timeout for this model; see Image API Essentials & Best Practices.

Text-to-Image API

/v1/images/generations, generate images from text prompts across all 5 FLUX.2 models.

Image Editing API

JSON input_image fields (up to 8 references for fusion, via /generations), plus an OpenAI-compatible multipart /edits single-image path. Works for FLUX.2 + FLUX.1 Kontext.

Historical Versions

Specs, migration notes, and pricing for FLUX.1 [pro] / [pro] 1.1 / [pro] 1.1 Ultra / [dev].

Why APIYI’s FLUX?

A drop-in replacement for the BFL official channel, optimized in stability, cost, and integration experience for production:

OpenAI-Compatible Wrapper · Zero-Code Migration

BFL native uses async polling, while APIYI wraps it as the synchronous OpenAI Images API. Point the OpenAI SDK’s base_url here — no need to write your own polling_url loop.

No Concurrency Cap · Beyond 24 Active Tasks

BFL caps each account at 24 active tasks (flux-kontext-max only 6). APIYI pools requests at the gateway, so enterprise users scale linearly without the per-account ceiling.

Same Price or Up to 17% Off

FLUX.2 [pro/max/flex] match the official price at 1MP, klein 4B/9B is ~28% cheaper, FLUX.1 [pro] 1.1 Ultra saves 17%, and stacking top-up bonuses yields up to 15% additional discount.

Global Zero-Friction Access

No overseas server or proxy required. Mainland China data centers, residential networks, and global nodes can all reach api.apiyi.com directly with stable latency.

Complete Model Ecosystem

Pair with gpt-image-2, Seedream, Nano Banana, and others on the same gateway — mix per scenario.

Professional Service · Enterprise Support

Our team has deep experience in image generation deployment — model selection, tuning, and integration support from PoC to production.

Key Features

Full Speed Spectrum

klein 4B/9B sub-second on consumer GPUs, pro < 10s, max < 15s, flex slower for higher precision. One family from real-time to flagship.

Native 4MP Output

Up to 2048×2048 (~4MP), 2.5x more than FLUX.1’s 1.6MP cap. Any aspect ratio (dimensions must be multiples of 16), minimum 64×64.

Multi-Reference Fusion

JSON fields input_image ~ input_image_8 carry multiple references (URL or base64 data URL): FLUX.2 [pro/max/flex] up to 8, [klein] up to 4. Reference them in the prompt as “image 1 / image 2”.

Grounding Search

Exclusive to FLUX.2 [max]: prompts can trigger real-time web search to render “yesterday’s match score”, “live weather”, “historical event recreation”, and more.

Precise Hex Color Control

Write hex codes like #02eb3c / #ff0088 directly in prompts. The model renders exact colors — no post-processing needed for brand-critical work.

32K-Token Long Prompts

Supports up to 32K tokens, including structured JSON descriptions (subject / background / lighting / style). Ideal for production automation.

Typography-Tuned

FLUX.2 [flex] is purpose-built for typography. Poster headers, UI mockups, infographics — small text fidelity leads the industry. max / pro also work well.

OpenAI SDK Drop-in

Set base_url to https://api.apiyi.com/v1 and call client.images.generate(model="flux-2-pro", ...) directly — zero code change.

Pricing

Per-image pricing — see the APIYI Price column. BFL’s official pricing is per MP (megapixel), with a base price within 1MP and incremental cost per extra MP. APIYI’s flat per-image pricing is more predictable.

FLUX.2 Series (Latest Generation)

Model ID	APIYI Price	Official	Speed	Best For
flux-2-max	$0.0700	from $0.07/MP	< 15s	Flagship quality + grounding search
flux-2-pro	$0.0300	from $0.03/MP	< 10s	Production at scale, best value
flux-2-flex	$0.0600	$0.06/MP	Slower	Typography-tuned, adjustable steps/guidance
flux-2-klein-9b	$0.0100	from $0.015	Sub-second	Balanced quality and speed
flux-2-klein-4b	$0.0100	from $0.014	Sub-second	Fastest, consumer-GPU friendly

FLUX.1 Kontext Series (Image Editing Specialist)

Model ID	APIYI Price	Official	Saves	Best For
flux-kontext-max	$0.0700	$0.08	12.5%	Highest editing quality, fine typography
flux-kontext-pro	$0.0350	$0.04	12.5%	Editing value pick, 5–6s generation

FLUX.1 [pro] Legacy (Historical, Still Callable)

Model ID	APIYI Price	Official	Saves
flux-pro-1.1-ultra	$0.0500	$0.06	17%
flux-pro-1.1	$0.0350	$0.04	12.5%
flux-pro	$0.0400	$0.04	Same
flux-dev	$0.0200	—	—

Detailed specs and migration guidance in the Historical Versions page.

Pricing Notes:

• APIYI uses flat per-image pricing — same cost regardless of output MP
• Official prices are MP-tiered: a base price for the first MP plus incremental cost per extra MP
• Editing requests cost the same as text-to-image (unlike OpenAI gpt-image-2 where edits are billed via Vision tokens)
• klein 4B / klein 9B open weights are available on Hugging Face for self-hosting (Apache 2.0 / FLUX NCL)
• Failed requests (4xx / moderation blocks) are not billed

Technical Specs

Dimension	Value
Recommended primary	flux-2-pro / flux-2-pro-preview (general) + flux-kontext-max (typography editing)
Speed	sub-second (klein) / < 10s (pro) / < 15s (max) / slower (flex)
Output resolution	Up to 4MP (2048×2048), any aspect ratio, dimensions must be multiples of 16
Input resolution	Min 64×64, max 4MP (editing endpoint only)
Reference images	8 (FLUX.2 [pro/max/flex]) / 4 (FLUX.2 [klein]) / 1 (FLUX.1 Kontext)
Prompt length	Up to 32K tokens
Output format	jpeg (default) / png
Moderation	safety_tolerance 0–6 (0 = strictest, 6 = most permissive, default 2)
Grounding search	Only flux-2-max
Response field	data[0].url (valid for 10 minutes, download immediately)
Images per request	1 (n=1)
prompt_upsampling	Supported on FLUX.2 [pro/max/flex], not on [klein]

API Endpoints

Endpoint	Purpose	Content-Type
POST /v1/images/generations	Text-to-image + image editing / multi-reference fusion (JSON input_image ~ input_image_8, recommended, all FLUX models)	application/json
POST /v1/images/edits	OpenAI-compatible single-image editing (client.images.edit() drop-in; verified on the Kontext series)	multipart/form-data

For multi-reference fusion, use /generations (JSON input_image_N). The /edits endpoint accepts a single image file only — best for migrating existing OpenAI SDK editing code.

Domain options: api.apiyi.com is the primary domain. Alternative gateway domains like b.apiyi.com / vip.apiyi.com behave identically.

Size (width / height) in Detail

Common Dimensions

Size	Aspect	Pixels	Best For
1024x1024	Square 1:1	~1MP	General, social avatars
1024x1536	Portrait 2:3	~1.6MP	Posters, portraits
1536x1024	Landscape 3:2	~1.6MP	Scenery, desktop
1440x2048	Portrait ~3:4	~2.9MP	Cinematic vertical
1920x1080	Landscape 16:9	~2MP	Video thumbnails
2048x2048	Square 1:1	4MP	Flagship print (FLUX.2 cap)

Custom Size Constraints

FLUX.2 accepts arbitrary dimensions, as long as all of the following hold:

1. width / height must be multiples of 16
2. Minimum 64×64
3. Maximum ~4MP (e.g., 2048×2048 / 1920×2048 / 2048×1920)
4. Recommended total ≤ 2MP to balance speed and cost

Valid examples: 1280x720, 1920x1080, 2048x1024, 1456x1920 Invalid examples: 1000x1000 (not multiple of 16), 3840x2160 (exceeds 4MP), 32x32 (below 64×64)

API: width/height vs OpenAI-compatible size: BFL natively uses integer width / height. APIYI also accepts the OpenAI-style size: "1024x1024" string. The two are equivalent — pick either.

Best Practices

1. Pick model by scenario

   Flagship final + needs real-time knowledge → flux-2-max. Production batch → flux-2-pro. Typography posters / infographics → flux-2-flex. High-throughput real-time → flux-2-klein-9b. Image editing → flux-kontext-max or flux-kontext-pro.

2. Default to ≤ 2MP

   The sweet spot for speed and cost is 1MP–2MP. Reach for 4MP only when truly needed (print, 4K screens). klein at high resolution increases per-call cost noticeably.

3. Reference images by index in prompts

   The numbering of input_image / input_image_2 / input_image_3 is exactly the “image 1 / image 2 / image 3” index in your prompt. Say “the person from image 1 in the scene of image 2 with the color palette of image 3” — far more reliable than letting the model guess.

4. Download result URLs immediately

   data[0].url is valid for only 10 minutes, hosted on delivery-eu.bfl.ai / delivery-us.bfl.ai, with CORS disabled. Production must server-side download to your own CDN.

5. Lock typography to flex or max

   Sign text, posters, UI screenshots — prefer flux-2-flex (typography specialist) or flux-2-max (highest overall quality). Other models may still blur small text.

6. Use max for grounding search

   Real-time knowledge (“today’s weather”, “last night’s match”) is supported only on flux-2-max. Other models rely on training data and cannot fetch live info.

7. Client timeout 60–120s

   APIYI handles polling internally and pro / max return in < 15s, but with queueing and network jitter set client timeout to 60–120s. flex can go up to 180s.

8. Fix seed for reproducibility

   Same seed + same other params = consistent results, useful for A/B tests and client review. klein doesn’t support prompt_upsampling; pro/max/flex have it off by default — opt in as needed.

Error Codes & Retries

Status	Meaning	Recommended Action
400	Invalid params (width/height not multiple of 16, exceeds 4MP, prompt over 32K tokens)	Validate against the size constraints, especially the 16-multiple rule
401	Invalid token	Check Bearer token
403	Moderation block	Adjust prompt or raise safety_tolerance (max 6)
429	Rate-limited / out of credits / active tasks exceeded	Exponential backoff retry
5xx	Gateway / backend error	Retry 1–2 times
Timeout	Long-tail	Client timeout ≥ 60s (flex up to 180s)

Recommended client config:

• Request timeout 60–120s (flex up to 180s)
• Exponential backoff for 5xx and 429 (recommended 2 retries)
• Once data[0].url is received, download asynchronously immediately — do not wait for user click
• Log the x-request-id response header for support

FAQ

Why does the url field expire in 10 minutes?

BFL hosts results on delivery-eu.bfl.ai / delivery-us.bfl.ai with signed URLs valid for 10 minutes, and CORS is disabled. Production services must server-side download to your own OSS / CDN. Don’t pass the original URL to browsers, and don’t expect users to access it later.

APIYI inherits the same URL mechanism — behavior matches the official channel.

The official API uses async polling — how does APIYI make it synchronous?

The APIYI gateway handles polling for you: you send a standard OpenAI Images API request, the gateway internally POSTs to BFL, polls polling_url until Ready, then wraps the final result.sample URL as data[0].url and returns. From the client’s perspective, it’s a single request-response — identical to OpenAI / GPT-Image / Nano Banana.

How many reference images can I send? How to write the prompt?

• FLUX.2 [pro/max/flex]: up to 8
• FLUX.2 [klein]: up to 4
• FLUX.1 Kontext [pro/max]: single reference (multi-image needs client-side stitching)

Reference them by index (“image 1 / image 2 / image 3”) in the prompt, e.g., “place the person from image 1 into the scene from image 2, applying the color palette of image 3”. Natural-language references also work — the model understands input images well.

What does prompt_upsampling do? Should I enable it?

prompt_upsampling=true makes the model auto-expand and refine your prompt (especially helpful for short prompts). But it changes the original intent — keep it off for brand work and on for free exploration.

Limitation: FLUX.2 [klein] doesn’t support it (silently ignored if passed).

How do I use grounding search?

Only flux-2-max supports it. No special parameter needed — if your prompt requires real-time knowledge, the model will automatically search the web before generating. Example:

“Generate a news photo of the snowstorm hitting NYC on Dec 15, 2025”

Great for “yesterday’s match score”, “live weather”, “historical event recreation”, “latest trends”. Prompts without time-sensitive content won’t trigger search and bill as normal generation.

What's the most effective way to use hex colors?

Write hex codes directly in the prompt with explicit “color” or “hex” markers:

A vase on a table, the color of the vase is gradient from #02eb3c to #edfa3c, the flowers have color #ff0088

Or for multi-color brand work:

Luxury eyeshadow palette with 6 pans: top row #B76E79, #E8D5B7, #8B4789; bottom row #CD7F32, #F8F6F0, #800020

Industry-leading precision — no post-processing color correction needed.

What's structured JSON prompting?

FLUX.2 supports JSON-formatted prompts:

{
  "subject": "Mona Lisa painting by Leonardo da Vinci",
  "background": "museum gallery wall, ornate gold frame",
  "lighting": "soft gallery lighting",
  "style": "digital art, high contrast",
  "camera_angle": "eye level view",
  "composition": "centered, portrait orientation"
}

Pass the JSON string as the prompt field. Ideal for production automation and templated batch generation.

Which endpoint should I use for image editing?

Two options:

• Option A (recommended): JSON + input_image (~ input_image_8) to /v1/images/generations — works for all FLUX models and supports multi-reference fusion
• Option B: multipart/form-data to /v1/images/edits — the file field name must be image (single image), directly compatible with the OpenAI SDK’s client.images.edit(), verified on the Kontext series

See Image Editing API for parameters and examples.

Note: FLUX.1 Kontext supports only single-reference natively; FLUX.2 supports up to 8 references (via Option A).

Can I use the OpenAI official SDK directly?

Yes, zero code change. Set base_url to https://api.apiyi.com/v1:

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
resp = client.images.generate(
    model="flux-2-pro",
    prompt="...",
    size="1024x1024"
)

Same for the Node.js openai package. All FLUX models follow the OpenAI Images API response shape with data[0].url.

Can I cancel a running task?

Not supported. If the client disconnects, the server still completes the generation and bills as normal. Set client-side timeouts and don’t rely on “disconnect = no charge”.

What are the rate limits and concurrency caps?

BFL caps each account at 24 active tasks, with flux-kontext-max separately limited to 6.

APIYI pools at the gateway, so enterprise concurrency is not bound by the per-account ceiling. For explicit SLA / RPM commitments, contact our team for a dedicated quota.

Do webhook callbacks work?

BFL natively supports webhook_url + webhook_secret, but APIYI’s OpenAI-compatible wrapper waits synchronously and does not pass through webhook fields — you don’t need to poll, request-response is one shot. If your business genuinely needs webhooks, contact us to enable a native async channel.

Are failed requests billed?

No. 400 (param error), 403 (moderation block), 429 (rate-limited) all return errors and are not billed. Only requests that actually enter generation (200 + data[0].url) are billed.

Related Docs

• Text-to-Image Playground — /v1/images/generations interactive debugger
• Image Editing Playground — multi-reference fusion + edit
• Historical Versions & Migration — FLUX.1 [pro] / [pro] 1.1 / Ultra / [dev]
• API Manual — general usage spec
• GPT-Image-2 Overview — OpenAI flagship, supports 4K
• Seedream Overview — BytePlus partnership channel

FLUX is BFL’s first-party model family, leading the industry in hex color precision, typography fidelity, and long-prompt understanding. If you prioritize OpenAI ecosystem compatibility, see GPT-Image-2; for Chinese-language scenarios, see Seedream.