Skip to content

Black Forest LabsImage modelChecking

FLUX 3 API

Model IDflux-3-text-to-image

FLUX 3 Image and FLUX 3 Image Klein generate images from text and support reference-based editing.

  • Text to image
  • Image to image
  • Up to 10 input images
  • 1.5K, 2K or 4K output
  • Format options

Run FLUX 3 in the playground

The form is the request body: every field shows its key. Sign in to run it; a run is billed like an API task.

Parameters

Model
model

FLUX 3Text to imageflux-3-text-to-image

Required
input.prompt

Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits. 1–20000 chars

input.resolution

Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP.

Common options
input.aspectRatio

Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image.

Advanced (2)
input.grounding

Allow web or image search before generation. On by default.

input.safetyTolerance

Moderation tolerance, 0 strictest to 4, default 2. 0–4

Estimated cost
Loading price…

Credits are reserved when a task is accepted and charged only on success. Failed tasks release the reservation; unconfirmed outcomes remain reserved until verified.

Request preview

{"model": "flux-3-text-to-image","input": {"aspectRatio": "1:1","resolution": "1k","grounding": true,"safetyTolerance": 2}}

The web playground sends this body with your signed-in session. From code, send the same body with an API key.

Result

Run the request and the result appears here, with its status and cost.

FLUX 3 pricing

Prices are shown in USD for each available variant and specification. The billing unit is shown with its rate; an official reference appears only when a matching list price is published.

Loading price…
  • Charged only on successOnly successful tasks are charged. Failed tasks release reserved credits; tasks with an unconfirmed outcome keep their reservation until the result is verified.
  • Safe retriesIdempotent retries with the same key do not create a second charge.
  • Price changesSend expectedPriceMicros to reject the task with PRICE_CHANGED if the price changed after you displayed it.

Compare FLUX 3 variants

Each variant has its own model ID and input schema. Pick the task first, then the tier. Additional fields are shown when variants differ.

  • Text to imageDefault

    flux-3-text-to-image

    Text to image; Text; 768sq, 1K, 1.5K, 2K, 4K; 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

    grounding
  • Image to image

    flux-3-image-to-image

    Image to image; Text, image; 768sq, 1K, 1.5K, 2K, 4K; 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

    grounding
  • Klein text to image

    flux-3-klein-text-to-image

    Text to image; Text; 768sq, 1K, 1.5K, 2K, 4K; 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

    seedstepsoutputFormat
  • Klein image to image

    flux-3-klein-image-to-image

    Image to image; Text, image; 768sq, 1K, 1.5K, 2K, 4K; 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

    seedstepsoutputFormat

What FLUX 3 can do

Black Forest Labs lists FLUX 3 Image and Image Klein as distinct image models. The manufacturer describes Klein as an open-weights member of the family for generation and multi-reference editing; its API or self-hosting terms should be checked separately.

The Hermes catalog groups standard and Klein text-to-image and image-to-image variants on this page. Their schemas list output tiers from 768sq through 4k; edit variants accept up to ten reference images. The standard variants also list a grounding option. Check the selected variant's status and price before making a request.

Black Forest Labs also describes bounding-box editing for its FLUX 3 Image product. Those controls are not listed in these Hermes request schemas; consult the selected variant's parameters rather than assuming every manufacturer feature is exposed here.

Capabilities

  • Format options

    The request schema lists these formats. Availability and delivery depend on the variant.

    JPEG · PNG

    outputFormat

    Variants: Klein text to image, Klein image to image

  • 1.5K, 2K or 4K output

    Pick the output resolution: 768sq, 1K, 1.5K, 2K or 4K.

    resolution

    Every variant

  • 15 aspect ratios

    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 or 9:21.

    aspectRatio

    Every variant

  • Up to 10 input images

    Send up to 10 images in one request as HTTPS URLs or uploaded media references.

    imageUrls

    Variants: Image to image, Klein image to image

  • Seed

    Accepts a seed value.

    seed

    Variants: Klein text to image, Klein image to image

Use cases

  1. Create image concepts

    Describe a scene or visual brief and select a resolution and aspect ratio.

  2. Edit from references

    Supply reference images and a prompt that states what should change.

  3. Compare model variants

    Try standard or Klein when each is available, using the same prompt and output requirements.

Call FLUX 3 from code

Every image, video and music model uses the same asynchronous job API: submit a task, then poll for the result.

  1. 1

    Create an API key

    In the dashboard, with the jobs:create and jobs:read scopes. API keys
  2. 2

    Submit a task

    POST /api/v1/jobs with the model ID and an input object. The response is 202 with a task ID.
  3. 3

    Poll for the result

    GET /api/v1/jobs/{id} until the status is succeeded, then download the output URLs.

Minimal request

Required fields only, generated from the schema of Text to image. Set HERMES_API_KEY in your environment.

Model ID
flux-3-text-to-image
Endpoint
https://api.hermes-ai.net/api/v1/jobs
Full task API reference
# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "flux-3-text-to-image",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light",
    "resolution": "1k"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"

Input parameters

Fields of Text to image (flux-3-text-to-image). Unknown fields are rejected with INVALID_MODEL_INPUT.

FieldTypeRequiredDefaultAllowed values and constraints
prompt
stringrequired—

Scene description or edit instruction. No negative prompt; a bbox JSON array may be appended for layout or local edits.

1–20000 chars

aspectRatio
stringoptional"1:1"

Output aspect ratio. auto follows the first reference image when editing, or the prompt for text-to-image.

One of: "auto", "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"

resolution
stringrequired"1k"

Resolution tier, decides the price. 768sq ~768x768, 1k ~1MP, 1.5k ~2MP, 2k ~4MP, 4k ~16MP.

One of: "768sq", "1k", "1.5k", "2k", "4k"

grounding
booleanoptionaltrue

Allow web or image search before generation. On by default.

safetyTolerance
integeroptional2

Moderation tolerance, 0 strictest to 4, default 2.

0–4

Headers, response, task statuses and errors
HeaderValueNotes
AuthorizationBearer <API key>Or send the key in x-api-key.
Content-Typeapplication/json
Idempotency-Key<unique string ≤128>Required. Reuse it only to retry the identical request.
FieldTypeNotes
idstringHermes AI task ID. Use it to poll.
modelstringModel slug.
statusstringSee task statuses.
errorCodestring | nullSet when a task fails or needs review.
priceMicrosintegerQuote fixed at admission, USD micro-units.
currency"USD"
createdAt / updatedAtstringISO 8601 timestamps.
assets[]array{ id, type, url?, text? }. url is a same-origin /api/v1/results/<uuid> link.
replayedbooleanSubmit only. true when an idempotent retry matched.
StatusTerminalMeaning
queuednoAccepted and waiting for a worker.
submittingnoBeing sent to the model provider.
runningnoThe model is generating.
succeededyesFinished. Results are in assets.
failedyesFinished without a result. The hold is released.
reconciliation_requiredyesThe result is being verified. Keep the task ID and do not resubmit automatically.
HTTPCodeMeaning and action
401AUTH_REQUIREDMissing or invalid API key or session.
403INSUFFICIENT_SCOPEThe API key lacks the scope this endpoint needs.
403PERMISSION_DENIEDThis credential cannot perform the operation.
429API_KEY_RATE_LIMITEDThe API key's rate limit was reached. Honor Retry-After.
429API_KEY_USAGE_EXCEEDEDThe API key reached its usage limit. Create a new key.
400INVALID_REQUESTThe body is not a JSON object or a required value is missing.
400INVALID_IDEMPOTENCY_KEYIdempotency-Key must be 1–128 printable ASCII characters.
400INVALID_MODEL_INPUTinput does not match the model schema (unknown field, missing required field, or invalid value).
400 / 413INPUT_TOO_LARGEThe request body is larger than 256 KB. Upload media first and send a media reference.
404REQUEST_NOT_FOUNDNo chat request with this ID belongs to your account.
404MODEL_NOT_FOUNDNo model has this slug.
404JOB_NOT_FOUNDNo task with this ID belongs to your account.
409IDEMPOTENCY_CONFLICTThis Idempotency-Key was used with different input. Use a new key for a new request.
409PRICE_CHANGEDThe price differs from expectedPriceMicros. Fetch the price and confirm again.
409MODEL_PRICE_UNAVAILABLENo price is configured for this model yet, so it cannot run.
409PAYMENT_REVIEW_REQUIREDA refund left an uncovered balance. Contact support or cover the balance before submitting tasks.
409INSUFFICIENT_CREDITSAvailable credits do not cover the task price.
429RATE_LIMITEDToo many task submissions per minute. Retry later.
429EXPORT_RATE_LIMITEDToo many CSV exports this minute. Honor Retry-After.
429CONCURRENCY_LIMITEDToo many unfinished tasks. Wait for one to finish.
503EXECUTION_UNAVAILABLEExecution is not configured for this model right now.
429UPSTREAM_RATE_LIMITEDThe model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
502UPSTREAM_ERRORThe model provider failed the chat request. Nothing was charged; retry later.
503PLATFORM_BUDGET_EXCEEDEDThis model is temporarily unavailable. Try again later.
503EXECUTION_TEMPORARILY_UNAVAILABLEExecution is temporarily unavailable. Retry with the same Idempotency-Key.
503AUTH_UNAVAILABLEAuthentication is temporarily unavailable. Retry later.
503API_UNAVAILABLEThe API is temporarily unavailable. Retry later.

FLUX 3 API FAQ

Answers built from the model's schema and the Hermes AI API contract.

Does this page cover FLUX 3 Video?

No. This family page covers image variants. FLUX 3 Video has separate text-to-video, image-to-video and continuation variants.

Can I use the manufacturer's bounding-box editor here?

The manufacturer describes bounding-box controls on its product page, but they are not exposed in the current Hermes schemas for these variants.

What can the FLUX 3 API do?

FLUX 3 by Black Forest Labs handles text to image and image to image. The catalog lists 4 variants, each with its own model ID and input schema. Check the current availability before sending a request.

Which durations, resolutions and aspect ratios does FLUX 3 support?

Across its variants, FLUX 3 supports 768sq, 1K, 1.5K, 2K and 4K resolution and aspect ratios 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 and 9:21. Each variant accepts its own subset; the variants table on this page lists them.

What input does FLUX 3 accept?

A text prompt of up to 20,000 characters, plus image input (up to 10 images per request). Media fields take a public HTTPS URL or a media:<uuid> reference returned by POST /api/v1/media, so local files can be uploaded first. Unknown fields are rejected with INVALID_MODEL_INPUT.

How is FLUX 3 priced and billed?

You pay per successful task from prepaid credits, with no subscription. The price depends on the variant and the specification you choose, such as resolution or duration; see the pricing table on this page or the pricing page. Credits are reserved when a task is accepted and charged only when it succeeds; a failed task returns the reservation to your balance.

Which FLUX 3 variant should I choose?

For text to image, Text to image and Klein text to image differ in fields: Text to image adds grounding; Klein text to image adds seed, steps, outputFormat; for image to image, Image to image and Klein image to image differ in fields: Image to image adds grounding; Klein image to image adds seed, steps, outputFormat. Pick the task first, then compare the tiers in the variants table.

How do I call the FLUX 3 API from code?

Send POST https://api.hermes-ai.net/api/v1/jobs with the variant's model ID and an input object, then poll GET /api/v1/jobs/{id} until the status is succeeded or failed. The API section has cURL, JavaScript and Python examples generated from the schema.

Can I try FLUX 3 without writing code?

Yes. Sign in and use the playground on this page: it sends the same request as the API with your session and charges the same price. Code needs an API key from the dashboard.

What happens when a task fails or I hit a rate limit?

A failed task is not charged and its reserved credits are returned. Too many submissions per minute return 429 RATE_LIMITED, and too many unfinished tasks return 429 CONCURRENCY_LIMITED; retry later or wait for a task to finish.