Guide
Using flux-3 for E-commerce Product Images via the HiAPI API
Prompt templates, background and lighting control, and a working request for product-shot generation
On this page
Why flux-3 fits e-commerce product imagery
Catalog pipelines fail for a boring reason: consistency. A product page is not one hero image, it is dozens of images across SKUs, angles, and seasonal refreshes, and they all have to look like they came from the same studio on the same afternoon. Handing each of those to a photographer is slow and expensive; handing each of them to an arbitrary image generator usually produces a set of images that each look plausible on their own and wrong together.
That is the gap flux-3 is useful for. It is an image generation model exposed through the HiAPI API, which means your product pipeline can treat image creation as another HTTP call: send a prompt plus your product parameters, get an image back, store it, move to the next SKU. No vendor-specific SDKs, no separate accounts per model, no per-provider glue code.
What matters for e-commerce specifically is that flux-3 responds predictably to prompt structure. A photograph of a product is a highly constrained scene: one subject, centered or deliberately composed, a clean backdrop, and studio-style lighting. Those constraints are exactly what you can put into words, and once they are in words they become template variables rather than creative decisions. That is the difference between "asking a model for a picture" and having a generation step in a catalog job.
The practical workflow in this guide is: define one reusable prompt structure, tune background and lighting wording until a baseline looks right, then swap the subject block per product. Everything else stays fixed, which is what buys you visual consistency across a product line.
What you need before starting
- A HiAPI API key and the current flux-3 model identifier from the platform's model list.
- Product data in structured form: name, material, color, shape, and any distinguishing details you want the model to render.
- A place to store the baseline prompt and the generated outputs, so you can diff versions later.

Anatomy of a product-shot prompt for flux-3
A prompt that works for one product is not much use. A prompt you can fill in is. The way to get there is to decompose the description into fixed blocks, each of which maps to a variable in your code.
The five blocks
- Subject. What the object is, in concrete nouns. "A matte ceramic coffee mug" beats "a nice mug." Include scale cues where they matter ("tall", "wide-rimmed").
- Material and surface. Finish and texture: brushed aluminum, glazed ceramic, woven cotton, frosted glass. This is where the model gets its specular highlights from, so be explicit.
- Background. The backdrop and surface the product sits on: seamless paper, stone slab, soft gradient, pure white sweep. Keep this block deliberately short and boring — it is scaffolding, not a creative slot.
- Lighting. Direction, quality, and contrast: soft key from the left, large diffused source, gentle fill, subtle shadow under the object. This block drives most of the "studio" feel and is the one you will tune most.
- Camera framing. How the shot is composed: centered product shot, eye level, three-quarter angle, tight crop, plenty of negative space above.
Turning blocks into a template
The blocks become a single string assembled at runtime, with only the subject (and occasionally material) swapped per SKU:
product photo of {subject}, {material}, {background}, {lighting}, {framing}
A filled example:
product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above
Two rules keep templates stable. First, keep the block order fixed — reordering blocks changes emphasis even when the words are identical. Second, keep the fixed blocks identical strings across SKUs rather than rephrasing them each time; small wording drift is the most common source of background and lighting inconsistency in a catalog.
Where creativity does not belong
Avoid editorial language in the fixed blocks: no mood adjectives, no styling flourishes, no references to scenes. Save any variation for intentional campaigns, and keep the catalog template clean. A template that reads like a technical spec produces images that look like a technical spec — which is precisely what a product listing needs.

Controlling background and lighting
Background and lighting are the two blocks that determine whether a set of images reads as one coherent catalog. Both respond well to concrete, physical wording.
Background: aim for boring
Describe the backdrop as a physical setup, not an aesthetic. "Seamless light gray paper backdrop" and "pure white infinity sweep" are reliable because they describe a known studio configuration. Words like "minimal" or "aesthetic" are vague and tend to let scene elements leak in.
Useful levers:
- Surface type: seamless paper, matte vinyl, natural stone slab, light wood.
- Color and tone: light gray, off-white, warm sand — keep the value mid-to-light so product edges stay readable.
- Continuity: "seamless" or "infinity" tells the model you want backdrop and floor to blend, removing horizon lines that are a pain to clean up later.
- Emptiness: "empty backdrop, no props" is worth stating explicitly if your earlier attempts introduced stray objects.
If you need transparent-background PNGs for a marketplace, generate on a clean uniform backdrop first and do the cutout in post. Asking an image model for true alpha is not the reliable path.
Lighting: direction first, quality second
Lighting wording splits cleanly into two decisions. Direction determines where highlights and shadows fall; quality determines how soft the edges of those highlights are.
- Direction: "key light from the upper left", "soft key from the front", "light from the right with a gentle fill on the left". Pick one and keep it for the whole line.
- Quality: "large diffused source", "soft shadows", "even illumination". Diffused, soft light is the safe default for product shots because it does not blow out glossy materials.
- Contact shadow: "soft contact shadow beneath the product" grounds the object; without it products can look like they are floating.
- Contrast: "low contrast, bright and even" suits marketplaces with white backgrounds; a little more directional contrast suits premium lifestyle crops.
Keeping a line consistent
Consistency is a versioning problem more than a prompting problem. Store the background and lighting blocks as named presets (for example, a "white studio" preset and a "stone slab" preset), and reference the preset by name in each generation job rather than pasting text per SKU. When you tune a preset, you tune it once and the next batch inherits the change deliberately instead of drifting.
When a result comes back wrong, change one block at a time and regenerate the same product. Changing background and lighting together makes it impossible to tell which wording did the work.

A working HiAPI request for flux-3
The generation step is a single API call. The exact endpoint path, model identifier, and request fields are documented on the platform and should be taken from there, since they can evolve; the shape below is the pattern to wire into your script.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
presets = {
"white_studio": {
"background": "on a pure white infinity sweep, no props, empty backdrop",
"lighting": "soft diffused key light from the upper left, even fill, "
"soft contact shadow beneath the product, low contrast",
"framing": "centered eye-level product shot, generous negative space",
}
}
def build_prompt(product, preset_name="white_studio"):
p = presets[preset_name]
return (
f"product photo of {product['subject']}, {product['material']}, "
f"{p['background']}, {p['lighting']}, {p['framing']}"
)
def generate(product, preset_name="white_studio"):
payload = {
"model": "flux-3", # confirm the current identifier in the model list
"prompt": build_prompt(product, preset_name),
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations", # see docs for exact path
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
product = {
"subject": "a matte ceramic coffee mug",
"material": "glazed stoneware with visible clay texture",
}
result = generate(product)
print(result)
Wiring it into a batch
A few habits make this safe to run over a catalog rather than a single product:
- Resolve every value from the environment. Keep the key out of source and out of logs.
- Treat the response as untrusted. Read the returned image reference or payload from the documented field, then download and store it in your own bucket. Do not depend on any temporary URL outliving the job.
- Record the exact prompt string with each output. Store it alongside the image metadata. When someone later asks why SKU 1234's shot looks different, the answer should be in your database, not in memory.
- Retry with backoff on transient failures, and cap concurrency so a large batch does not trip rate limits.
- Keep the request idempotent per SKU and prompt version, so a rerun overwrites the same output slot instead of scattering duplicates.
Iterating from template to production pipeline
The first validated prompt is a baseline, not a finished asset. Productionizing means turning it into something your pipeline can reproduce and audit.
Step 1: Lock a baseline on a small sample
Generate five to ten products from different material categories — one glossy, one matte, one fabric, one metallic, one transparent. These stress the lighting block in different ways. If the template holds across that sample, you have a baseline; if glossy products blow out or fabric looks flat, tune that block now rather than after a catalog run.
Step 2: Name and version the preset
Give the preset an explicit version identifier and treat changes as new versions, not edits. A simple white_studio_v1 → white_studio_v2 scheme lets you regenerate a batch under the old preset and compare, and lets you roll back if a "small improvement" turns out to be a regression on half your SKUs.
Step 3: Store prompts where the pipeline can read them
Keep two layers: the shared preset definitions (background, lighting, framing, version) in one place, and the per-SKU subject and material fields in your product database. Generation code then composes the two. This means a preset change propagates to every future job, while subject data stays owned by the catalog team.
Step 4: Compare outputs systematically
Side-by-side review does not scale past a few dozen SKUs. Cheaper signals:
- Contact-sheet review: tile a batch into one grid image and scan for outliers. Drifting backgrounds and shifted framing jump out immediately at thumbnail size.
- Edge sampling for background checks: sample pixel colors near the image border and flag results whose corners differ from the preset's expected tone. This catches the most common failure — a backdrop that quietly changed color — without human eyes.
- Frame-position checks: if products should sit centered with negative space above, measure where the subject mass falls in each image and flag outliers.
Anything flagged goes to a review queue; everything else publishes automatically.
Step 5: Regenerate deliberately
Once the baseline is stable, new SKUs are a data problem, not a prompt problem: add the subject and material fields, queue the job, let the automation sort it. Save regeneration runs for intentional changes — a seasonal backdrop, a new lighting variant — and bump the preset version when you do.
Common pitfalls and how to avoid them
Most failures in generated product imagery are the same handful of problems, and each has a prompt-side or pipeline-side fix.
Background drift across a batch
The most frequent complaint: images look consistent individually but vary from SKU to SKU. Almost always the cause is wording drift — someone rephrased the background block, or the template interpolated a product attribute into it. Fix: keep background and lighting as fixed strings from a single preset source, and assert in code that the assembled prompt contains the preset text verbatim.
Stray props and scene elements
Models like to add context: a sprig of leaves, a folded cloth, a shadow that looks like a table edge. Explicitly state emptiness ("empty backdrop, no props") and keep the scene language as physical and studio-bound as possible. If it persists, simplify the subject description — decorative adjectives in the subject block often invite matching decoration in the scene.
Floating products
No contact shadow makes an object look pasted onto the backdrop. Include "soft contact shadow beneath the product" in the lighting block, and specify that the product sits on a surface rather than hovering.
Inconsistent framing
Mixed crops ruin a category page. Pin the framing block to one phrase and do not let it vary; if you need multiple aspect ratios, generate the same composition and crop in post rather than prompting for each ratio.
Over-specified prompts
Long prompts that describe the product's history, brand, and story tend to produce editorial imagery, not catalog imagery. The template should read like a shot list. When results feel off, the fix is usually to remove words, not add them.
Treating a failed generation as a code bug
A single bad result is not a signal to rewrite the pipeline. Reproduce it with the exact stored prompt string, change one block, and regenerate before concluding anything. Keeping the prompt recorded with every output is what makes this possible — and it is the cheapest habit to adopt early.
Start with one preset, one sample batch, and a stored prompt per image; scale once the baseline holds across material types.
Related articles
View all articles →-
Guide
gpt-6.2-sol Getting Started Guide: Capability Boundaries, API Integration, and Token Pricing Essentials
Integration decisions and practical essentials for engineering teams
-
Guide
gpt-6.2-astra Getting Started Guide: Text Model Capability Boundaries, Integration Essentials, and Cost Control
-
Guide
Tripo H3.1 Getting Started Guide: Choosing Among Three Input Modes, Parameters, and Pricing
A practical guide for developers on 3D generation integration decisions and cost control