Blog

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

Nov 12, 2026 12 min read
Cover art in engraved hatching style: copper parallel lines on midnight blue form abstract product frames and a stepped pipeline.
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.
One product, rendered identically across nine controlled backdrops — the catalog-consistency promise of flux-3.

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.

Each prompt block — subject, material, background, lighting, framing — is an interchangeable slab you can reorder and reuse.

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.

Light-direction arrows and background swatch samples: how prompt wording maps to a consistent product-line look.

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 →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs