FLUX.2 Pro API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	flux-2/text-to-image
Type	Image generation (text-to-image)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Black Forest Labs' flagship text-to-image model: photorealistic fidelity with consistent lighting, strong adherence to complex multi-part prompts, legible in-image text down to small sizes with hex-code color control, priced by 0.5-4 MP resolution tier.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Product shots and commercial photography

Sharper material textures and consistent lighting suit e-commerce product shots and ad still lifes. For photorealism, add camera, lens and film language to the prompt (e.g. "Shot on Fujifilm X-T5, 35mm f/1.4").

promptresolution

Posters and UI mockups with text

In-image text is reliable down to small font sizes, per the official release — suited for titled posters, infographics and UI mockups. Write the exact copy and its placement directly into the prompt.

promptaspect_ratio

Exact brand colors

Specify colors with hex codes (e.g. #3B2A1A) right in the prompt, so brand key visuals match the palette exactly instead of relying on vague descriptions like "dark brown".

prompt

Complex multi-element compositions

Adherence to multi-part instructions and compositional constraints (element placement, spatial relationships) is markedly improved; complex scenes can also be described with structured JSON prompts. Fix the seed to keep a composition stable across iterations.

promptseed

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "A tall frosted glass perfume bottle centered on polished wet white marble, amber liquid glowing through matte glass, a slim gold cap catching the light, soft diffused window light from the left, minimal composition with generous negative space, shot on Hasselblad X2D, 90mm lens at f/2.8, shallow depth of field, crisp commercial product photography",
    "aspect_ratio": "4:5",
    "resolution": "2 MP"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "A tall frosted glass perfume bottle centered on polished wet white marble, amber liquid glowing through matte glass, a slim gold cap catching the light, soft diffused window light from the left, minimal composition with generous negative space, shot on Hasselblad X2D, 90mm lens at f/2.8, shallow depth of field, crisp commercial product photography",
    "aspect_ratio": "4:5",
    "resolution": "2 MP"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "A tall frosted glass perfume bottle centered on polished wet white marble, amber liquid glowing through matte glass, a slim gold cap catching the light, soft diffused window light from the left, minimal composition with generous negative space, shot on Hasselblad X2D, 90mm lens at f/2.8, shallow depth of field, crisp commercial product photography",
    "aspect_ratio": "4:5",
    "resolution": "2 MP"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value flux-2/text-to-image.

example flux-2/text-to-image

input object required

Business parameters. Put FLUX.2 Pro-specific configuration here.

prompt string required

Text prompt for image generation. Official guidance: put the most important elements first (word order affects weighting); 30-80 words works best.

aspect_ratio enum optional

Aspect ratio for the generated image. Choose custom with width/height for exact dimensions.

default 1:1 enum: 1:116:93:22:34:55:49:163:44:3custom

width integer optional

Custom width, only used when aspect_ratio is custom. Range 256-2048, automatically rounded to the nearest multiple of 16.

height integer optional

Custom height, only used when aspect_ratio is custom. Range 256-2048, automatically rounded to the nearest multiple of 16.

resolution enum optional

Output resolution tier in megapixels, up to 4 MP. Ignored when aspect_ratio is custom. The hosted provider recommends 2 MP or below for the most reliable results.

default 1 MP enum: 0.5 MP1 MP2 MP4 MP

output_format enum optional

Format of the output image.

default webp enum: webpjpgpng

output_quality integer optional

Compression quality when saving the image, 0-100. Only applies to lossy formats (webp/jpg); no effect on png.

default 80

safety_tolerance integer optional

Safety tolerance: 1 is the strictest, 5 the most permissive. Default 2.

default 2

seed integer optional

Random seed. Set for reproducible generation.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Brand poster with text and hex colors

Headline, subheading and three hex codes written directly into the prompt to exercise text rendering and exact color control; png avoids compression artifacts around the type.

Request body

{
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "A minimalist coffee brand poster: a matte ceramic pour-over cup of black coffee with a thin curl of steam, headline 'MORNING RITUAL' in large elegant uppercase serif type in deep espresso brown #3B2A1A, subheading 'SLOW BREW · SMALL BATCH' in a thin sans-serif in soft taupe #8A7660, vast warm beige background #EDE3D2 with generous negative space, soft window light from the upper left, modern editorial product photography",
    "aspect_ratio": "2:3",
    "resolution": "2 MP",
    "output_format": "png"
  }
}

Golden-hour realistic portrait

Film, lens and aperture language (Kodak Portra 400, 85mm f/1.8) controls the photographic finish and depth of field.

Request body

{
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "A young woman in profile, face turned three-quarters toward warm light, loose strands of hair drifting across her cheek, calm unguarded expression. Cinematic realistic portrait on a quiet open field at dusk, backlit by low golden-hour sun with rim light glowing amber through flyaway hair. Shot on Kodak Portra 400, 85mm lens at f/1.8, shallow depth of field, natural film grain, warm organic palette",
    "aspect_ratio": "4:5",
    "resolution": "1 MP"
  }
}

Custom-size e-commerce product shot

aspect_ratio=custom with width/height sets exact pixels (256-2048, rounded to the nearest multiple of 16); the resolution parameter is ignored in this mode.

Request body

{
  "model": "flux-2/text-to-image",
  "input": {
    "prompt": "Matte black wireless over-ear headphones standing upright on a glossy dark acrylic surface, rim-lit edges, soft gradient charcoal background, studio product photography, 100mm macro lens at f/5.6, crisp reflections and fine texture detail",
    "aspect_ratio": "custom",
    "width": 1200,
    "height": 1600
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated image from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

How is FLUX.2 Pro priced?

Billed by resolution tier — 0.5 MP / 1 MP / 2 MP / 4 MP — with higher tiers costing more per image; aspect ratio does not affect the price. See the live pricing page for current rates. View live pricing

Why is there no negative_prompt parameter?

FLUX.2 does not support negative prompts. Writing negations like "no X" in the prompt can backfire — the model may add that element instead. Describe what you want positively, and put the most important elements first.

Which resolution tier should I choose?

The hosted provider recommends 2 MP or below for the most reliable results, so 1-2 MP covers everyday work; reserve 4 MP for print-grade delivery. Note the 2048px per-side cap means non-square ratios may not reach the target megapixels at the highest tier.

How do I use custom dimensions?

Set aspect_ratio to custom and pass width and height (256-2048); values are automatically rounded to the nearest multiple of 16, and the resolution parameter is ignored. Use it only when you need exact pixels — preset ratios plus a resolution tier cover most cases.

FLUX.2 Pro API

Model summary

Production guidance

Best suited for

Request parameters

Example requests

Getting the result

FAQ

How is FLUX.2 Pro priced?

Why is there no negative_prompt parameter?

Which resolution tier should I choose?

How do I use custom dimensions?

Next steps