Skip to main content

​
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.

Text-to-Image API

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

Image Editing API

/v1/images/edits, multipart upload up to 8 reference images + edit/fusion instructions. 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

image[] array with multiple reference images: 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 IDAPIYI PriceOfficialSpeedBest For
flux-2-max$0.0700from $0.07/MP< 15sFlagship quality + grounding search
flux-2-pro$0.0300from $0.03/MP< 10sProduction at scale, best value
flux-2-flex$0.0600$0.06/MPSlowerTypography-tuned, adjustable steps/guidance
flux-2-klein-9b$0.0100from $0.015Sub-secondBalanced quality and speed
flux-2-klein-4b$0.0100from $0.014Sub-secondFastest, consumer-GPU friendly

​
FLUX.1 Kontext Series (Image Editing Specialist)

Model IDAPIYI PriceOfficialSavesBest For
flux-kontext-max$0.0700$0.0812.5%Highest editing quality, fine typography
flux-kontext-pro$0.0350$0.0412.5%Editing value pick, 5–6s generation

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

Model IDAPIYI PriceOfficialSaves
flux-pro-1.1-ultra$0.0500$0.0617%
flux-pro-1.1$0.0350$0.0412.5%
flux-pro$0.0400$0.04Same
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

DimensionValue
Recommended primaryflux-2-pro / flux-2-pro-preview (general) + flux-kontext-max (typography editing)
Speedsub-second (klein) / < 10s (pro) / < 15s (max) / slower (flex)
Output resolutionUp to 4MP (2048×2048), any aspect ratio, dimensions must be multiples of 16
Input resolutionMin 64×64, max 4MP (editing endpoint only)
Reference images8 (FLUX.2 [pro/max/flex]) / 4 (FLUX.2 [klein]) / 1 (FLUX.1 Kontext)
Prompt lengthUp to 32K tokens
Output formatjpeg (default) / png
Moderationsafety_tolerance 0–6 (0 = strictest, 6 = most permissive, default 2)
Grounding searchOnly flux-2-max
Response fielddata[0].url (valid for 10 minutes, download immediately)
Images per request1 (n=1)
prompt_upsamplingSupported on FLUX.2 [pro/max/flex], not on [klein]

​
API Endpoints

EndpointPurposeContent-Type
POST /v1/images/generationsText-to-image (all FLUX models)application/json
POST /v1/images/editsImage edit / multi-reference fusion (FLUX.2 + Kontext)multipart/form-data
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

SizeAspectPixelsBest For
1024x1024Square 1:1~1MPGeneral, social avatars
1024x1536Portrait 2:3~1.6MPPosters, portraits
1536x1024Landscape 3:2~1.6MPScenery, desktop
1440x2048Portrait ~3:4~2.9MPCinematic vertical
1920x1080Landscape 16:9~2MPVideo thumbnails
2048x2048Square 1:14MPFlagship 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 order of image[] becomes the index reference. 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

StatusMeaningRecommended Action
400Invalid params (width/height not multiple of 16, exceeds 4MP, prompt over 32K tokens)Validate against the size constraints, especially the 16-multiple rule
401Invalid tokenCheck Bearer token
403Moderation blockAdjust prompt or raise safety_tolerance (max 6)
429Rate-limited / out of credits / active tasks exceededExponential backoff retry
5xxGateway / backend errorRetry 1–2 times
TimeoutLong-tailClient 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

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 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.
  • 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.
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).
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.
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.
Use /v1/images/edits with multipart/form-data and upload image[] + prompt. See Image Editing API for parameters and examples.Note: FLUX.1 Kontext supports only single-reference natively; FLUX.2 supports up to 8 references.
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.
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”.
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.
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.
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.
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.