FLUX 3 Image is Black Forest Labs’ image-generation and editing model with explicit control over composition. A text description can create a new scene; supplied images can establish a subject, a scene to revise or several elements to combine. Bounding boxes let a brief specify where each element belongs and which parts of an existing image should change. The result is an image, with the requested scene, text and layout to inspect.
For a new image, describe the subject, action or pose, setting, light and framing. Put exact in-image wording in quotation marks and state where it appears. An original product brief could show a red camping mug on a pale stone surface, with a large headline above it and soft morning light revealing the handle. Define the relationship between the headline, product and background rather than offering unrelated style words.
For editing, identify the particular object and the change: recolor the mug, replace a label, move a figure or restyle the scene. A single edit does not require a manually drawn box. The documented workflow expands the instruction before generation and can locate the named element and add a box automatically. Its returned expanded prompt records that interpretation, which is useful when an instruction selects the wrong object or introduces an unwanted detail.
The exact producer profile accepts one to ten references, supplied as image URLs or encoded image data. Each must be at least 256×256 pixels and no larger than 16 megapixels. Name a reference by its position or visible content, then explain its role: the person from Image 1, the jacket from Image 2 and the room from Image 3. An image reference is a source of visual information, not an instruction to copy every unrelated detail it contains.
The aspect-ratio setting defaults to auto. In the request specification, a ratio requested in the prompt takes priority; otherwise the first reference establishes the framing, with square output as the fallback when neither a reference nor a requested shape supplies it. For a composite, place the intended scene reference first or choose the ratio explicitly. Keep the source images and their order with the result so a later revision uses the same visual starting point.
A layout prompt combines a caption with a JSON array of element rows. The caption names an element through a marker such as <cup_1>; the row contains id, bbox and desc. Coordinates are integers from 0 to 1000 in the order [top, left, bottom, right], measured from the top-left corner. For example, [0, 0, 500, 500] describes the top-left quarter regardless of the image’s pixel dimensions. Use the aspect ratio for which the layout was designed, because that coordinate grid stretches with the frame.
An edit row instead uses from, src_bbox and tgt_bbox alongside the identifier and description. ref_image_0 means the first supplied image. Matching source and target boxes anchor an element; different boxes move or resize it. A new row with no source generates its description at the target location, allowing additions, replacements or recoloring. A source row with no target removes the element. State additions and removals in both the written instruction and the rows, and retain anchor rows for details that must stay in place.
Give lettering its own box and quote its exact wording in desc. Boxes guide placement and scale; they are not clipping masks, so an element can extend beyond the rectangle. The maker reports that new objects in boxes around 40×25 pixels often failed to appear in its examples. Allow enough visible space, and inspect the edited boundaries. Pixels outside the target usually remain stable, but shadows, reflections and nearby lighting can still change.
The documented profile enables grounding by default, allowing web and image search to inform the generation. It can be disabled for a brief that should use only its supplied description and references. For a real-world subject, identify the location, event or object clearly and keep factual content separate from artistic treatment. Search-informed imagery still needs to be compared with authoritative material when a label, object or depicted event must be accurate.
The five resolution classes are 768sq, 1k, 1.5k, 2k and 4k, with 1k as the default. They represent equal-pixel-area tiers, so the exact width and height depend on the selected ratio. Fifteen fixed ratios range from 21:9 through square and portrait formats to 9:21. This model’s profile controls size through ratio and resolution; it does not expose the seed, width or height fields used in the FLUX.2 request profiles. Its documented version selector currently names a moving release rather than establishing a dated supplier-weight match.
The producer workflow returns an image after asynchronous processing, together with the expanded prompt. Its signed image download link is valid for one hour. Preserve the actual image, final prompt and references rather than relying on a temporary link. For a reviewed asset, compare the requested text, object placement, reference identity and changed region at the intended display size. A completed generation is the starting point for checking those visual requirements.
", "aboutText": "FLUX 3 Image is Black Forest Labs’ image-generation and editing model with explicit control over composition. A text description can create a new scene; supplied images can establish a subject, a scene to revise or several elements to combine. Bounding boxes let a brief specify where each element belongs and which parts of an existing image should change. The result is an image, with the requested scene, text and layout to inspect.\n\n### Create a scene or give an edit instruction\n\nFor a new image, describe the subject, action or pose, setting, light and framing. Put exact in-image wording in quotation marks and state where it appears. An original product brief could show a red camping mug on a pale stone surface, with a large headline above it and soft morning light revealing the handle. Define the relationship between the headline, product and background rather than offering unrelated style words.\n\nFor editing, identify the particular object and the change: recolor the mug, replace a label, move a figure or restyle the scene. A single edit does not require a manually drawn box. The documented workflow expands the instruction before generation and can locate the named element and add a box automatically. Its returned expanded prompt records that interpretation, which is useful when an instruction selects the wrong object or introduces an unwanted detail.\n\n### Combine and prepare reference images\n\nThe exact producer profile accepts one to ten references, supplied as image URLs or encoded image data. Each must be at least 256×256 pixels and no larger than 16 megapixels. Name a reference by its position or visible content, then explain its role: the person from Image 1, the jacket from Image 2 and the room from Image 3. An image reference is a source of visual information, not an instruction to copy every unrelated detail it contains.\n\nThe aspect-ratio setting defaults to auto. In the request specification, a ratio requested in the prompt takes priority; otherwise the first reference establishes the framing, with square output as the fallback when neither a reference nor a requested shape supplies it. For a composite, place the intended scene reference first or choose the ratio explicitly. Keep the source images and their order with the result so a later revision uses the same visual starting point.\n\n### Place elements with bounding boxes\n\nA layout prompt combines a caption with a JSON array of element rows. The caption names an element through a marker such asblack-forest-labs/flux-3-imageFLUX 3 Image creates and edits images from a written brief and up to ten references. It adds prompt-based bounding boxes for composition and local changes, web and image grounding, and five resolution classes.
This description covers the model’s capabilities. Available in Ailoot inputs, outputs and options are listed for the selected method below.
FLUX 3 Image is Black Forest Labs’ image-generation and editing model with explicit control over composition. A text description can create a new scene; supplied images can establish a subject, a scene to revise or several elements to combine. Bounding boxes let a brief specify where each element belongs and which parts of an existing image should change. The result is an image, with the requested scene, text and layout to inspect.
For a new image, describe the subject, action or pose, setting, light and framing. Put exact in-image wording in quotation marks and state where it appears. An original product brief could show a red camping mug on a pale stone surface, with a large headline above it and soft morning light revealing the handle. Define the relationship between the headline, product and background rather than offering unrelated style words.
For editing, identify the particular object and the change: recolor the mug, replace a label, move a figure or restyle the scene. A single edit does not require a manually drawn box. The documented workflow expands the instruction before generation and can locate the named element and add a box automatically. Its returned expanded prompt records that interpretation, which is useful when an instruction selects the wrong object or introduces an unwanted detail.
The exact producer profile accepts one to ten references, supplied as image URLs or encoded image data. Each must be at least 256×256 pixels and no larger than 16 megapixels. Name a reference by its position or visible content, then explain its role: the person from Image 1, the jacket from Image 2 and the room from Image 3. An image reference is a source of visual information, not an instruction to copy every unrelated detail it contains.
The aspect-ratio setting defaults to auto. In the request specification, a ratio requested in the prompt takes priority; otherwise the first reference establishes the framing, with square output as the fallback when neither a reference nor a requested shape supplies it. For a composite, place the intended scene reference first or choose the ratio explicitly. Keep the source images and their order with the result so a later revision uses the same visual starting point.
A layout prompt combines a caption with a JSON array of element rows. The caption names an element through a marker such as <cup_1>; the row contains id, bbox and desc. Coordinates are integers from 0 to 1000 in the order [top, left, bottom, right], measured from the top-left corner. For example, [0, 0, 500, 500] describes the top-left quarter regardless of the image’s pixel dimensions. Use the aspect ratio for which the layout was designed, because that coordinate grid stretches with the frame.
An edit row instead uses from, src_bbox and tgt_bbox alongside the identifier and description. ref_image_0 means the first supplied image. Matching source and target boxes anchor an element; different boxes move or resize it. A new row with no source generates its description at the target location, allowing additions, replacements or recoloring. A source row with no target removes the element. State additions and removals in both the written instruction and the rows, and retain anchor rows for details that must stay in place.
Give lettering its own box and quote its exact wording in desc. Boxes guide placement and scale; they are not clipping masks, so an element can extend beyond the rectangle. The maker reports that new objects in boxes around 40×25 pixels often failed to appear in its examples. Allow enough visible space, and inspect the edited boundaries. Pixels outside the target usually remain stable, but shadows, reflections and nearby lighting can still change.
The documented profile enables grounding by default, allowing web and image search to inform the generation. It can be disabled for a brief that should use only its supplied description and references. For a real-world subject, identify the location, event or object clearly and keep factual content separate from artistic treatment. Search-informed imagery still needs to be compared with authoritative material when a label, object or depicted event must be accurate.
The five resolution classes are 768sq, 1k, 1.5k, 2k and 4k, with 1k as the default. They represent equal-pixel-area tiers, so the exact width and height depend on the selected ratio. Fifteen fixed ratios range from 21:9 through square and portrait formats to 9:21. This model’s profile controls size through ratio and resolution; it does not expose the seed, width or height fields used in the FLUX.2 request profiles. Its documented version selector currently names a moving release rather than establishing a dated supplier-weight match.
The producer workflow returns an image after asynchronous processing, together with the expanded prompt. Its signed image download link is valid for one hour. Preserve the actual image, final prompt and references rather than relying on a temporary link. For a reviewed asset, compare the requested text, object placement, reference identity and changed region at the intended display size. A completed generation is the starting point for checking those visual requirements.
POST /v1/images/generationstext, imageimage| Field | Type | Requirement | Values & limits | Default |
|---|---|---|---|---|
Fieldmodel | Typestring | RequirementRequired | Values & limits black-forest-labs/flux-3-image | Default— |
Fieldprompt | Typestring | RequirementRequired | Values & limits Minimum length: 1 | Default— |
Fieldresolution | Typestring | RequirementOptional | Values & limits 768, 1K, 1.5K, 2K, 4K | Default— |
Fieldaspect_ratio | Typestring | RequirementOptional | Values & limits 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21, auto | Default— |
Fieldn | Typeinteger | RequirementOptional | Values & limits Minimum: 1 Maximum: 1 | Default— |
Fieldinput_references | Typearray | RequirementOptional | Values & limits Minimum items: 0 Maximum items: 10 | Default— |
Fieldprovider | Typeobject | RequirementOptional | Values & limits | Default— |
| Parameter | Contract |
|---|---|
Parametercontent_type | Contractapplication/json |
Parameterrequired | Contractmodel, prompt |
Parametermaterial_types | Contracttext, image |
Lifecycle: synchronous_result_then_owned_library
GET /v1/media/tasks/{task_id} · actual returned task_id or media library record
GET /v1/media/assets/{asset_id}/content
GET /v1/media/assets
GET /v1/media/assets/{asset_id}
The displayed rates estimate the cost before generation. The final charge is calculated from the cost recorded for the original generation. Measured output duration and forecast quantities are not the final billable quantity.
Tariff references do not add request options. Supported parameters are listed for the selected method.
Match each charge to the conditions shown. Use one rate for each set of alternative configurations.
| Configuration | Rate schedule | Forecast quantity | Charge |
|---|---|---|---|
| ConfigurationBase token rates | Rate scheduleBase rate | Forecast quantity— | Charge Input · Input tokens · Estimate for comparison only — / 1K tokens Output · Output tokens · Estimate for comparison only — / 1K tokens Input · Cache read · Estimate for comparison only — / 1K tokens Input · Cache write · Estimate for comparison only — / 1K tokens Input · Cache write, 1 hour · Estimate for comparison only — / 1K tokens |
| ConfigurationEstimated generation cost | Rate schedule— | Forecast quantityone generation estimate | Charge Output · Estimated generation cost · Estimate for comparison only $0.082 estimate before generation This estimate is not an additional charge or a fixed rate for the completed generation. |
Ailoot reserves an estimated amount before a request. After the result, it settles the final charge from measured usage. Streaming settlement uses the final usage record. How reservation and settlement work →
set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\nexport AILOOT_API_KEY\npython3 - <<'PY_REQUEST'\nimport json,os\nfrom pathlib import Path\np={'model': 'black-forest-labs/flux-3-image', 'prompt': 'a red panda astronaut floating in space, studio lighting'}\n\nPath("request.json").write_text(json.dumps(p,ensure_ascii=False))\nPY_REQUEST\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/images/generations \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -H 'Content-Type: application/json' \\\n --data-binary @request.json -D response-headers.txt -o result.json\npython3 - <<'PY_RESULT'\nimport base64, json, os, subprocess\nfrom pathlib import Path\nfrom urllib.parse import urlsplit, urljoin\n\ndef save_images(items):\n if not items: raise SystemExit("No completed images; retain the full response")\n for index, item in enumerate(items):\n encoded=item.get("b64_json")\n uri=item.get("url", "")\n if not encoded and uri.startswith("data:image/"):\n header, separator, encoded=uri.partition(",")\n if not separator or ";base64" not in header: raise SystemExit("Unsupported image data URI")\n if encoded:\n raw=base64.b64decode(encoded,validate=True)\n elif uri:\n uri=urljoin("https://api.ailoot.ai",uri)\n parsed=urlsplit(uri)\n if parsed.scheme!="https" or not parsed.netloc or parsed.username or parsed.password:\n raise SystemExit("Invalid returned image URL")\n owned=parsed.netloc=="api.ailoot.ai" and parsed.path.startswith("/v1/media/assets/") and parsed.path.endswith("/content")\n args=["curl","--fail-with-body","--silent","--show-error",uri]\n if owned: args += ["-H","Authorization: Bearer "+os.environ["AILOOT_API_KEY"]]\n temporary=Path(f"image-{index}.bin")\n subprocess.run(args+["-o",str(temporary)],check=True)\n raw=temporary.read_bytes()\n temporary.unlink()\n else: raise SystemExit("Image has neither bytes nor URL")\n if not raw: raise SystemExit("Empty image result")\n ext="png" if raw.startswith(b"\\x89PNG") else "jpg" if raw.startswith(b"\\xff\\xd8") else "webp" if raw[:4]==b"RIFF" and raw[8:12]==b"WEBP" else "svg" if raw.lstrip().startswith((b"<svg",b"<?xml")) else "bin"\n Path(f"image-{index}.{ext}").write_bytes(raw)\n print("Every returned image saved; complete response metadata retained")\nsave_images(json.loads(Path("result.json").read_text())["data"])\nPY_RESULT\nDownload each returned image or save its Base64 contents
GET /v1/media/tasks/{task_id}GET /v1/media/assets/{asset_id}/contentGET /v1/media/assetsGET /v1/media/assets/{asset_id}set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/media/assets \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -o owned-assets.json\n# Preserve every returned asset and follow its exact signed content URL. Do not construct a signed token.\nSave every completed image; retrieve each returned URL or decode its Base64 contents.
Retain the complete response and headers, every actual output, original returned identifiers and all usage fields. Recover the original operation without submitting creation again.
Keep the returned X-Client-Request-ID for reconciliation. Read only actual returned task_id/asset_id values or the owned media library; never build a task URL from the operation ID and never resubmit creation.
| Field | Type |
|---|---|
Fieldcreated | Type |
Fielddata[].url | Type |
Fielddata[].b64_json | Type |
Fieldusage | Type |
Ailoot Ultra black-forest-labs/flux-3-image
/v1/images