Using qwen-image-2.1-pro for E-commerce Product Images: API Usage and Prompt Recipes

Why qwen-image-2.1-pro for product imagery

E-commerce image work is rarely one job. It is a catalog shoot for a new SKU, a cutout for a marketplace listing, a lifestyle scene for a landing page, and a banner with a promo badge — usually all due the same week. qwen-image-2.1-pro is worth evaluating when your pipeline has to produce all of those from the same product data, because it handles generation, editing of existing assets, transparent PNG output, and on-image text in one model rather than a chain of specialty tools.

Three task shapes cover most of the workload:

• Transparent cutouts — the product isolated on a clean transparent background, ready to drop onto any surface in your CMS.
• Scene composition — the product placed in a plausible lifestyle or studio context, generated from a text description plus a reference.
• Text-bearing layouts — labels, badges, and banners where words must come out readable and correctly placed.

Where it does not replace a studio: hero imagery with strict brand-lighting requirements, and any asset where the product's exact geometry is legally constrained (regulated packaging, for instance). Treat generation as a way to expand coverage and speed up iteration, then keep a human approval gate — which is exactly what the review loop later in this guide is for.

The practical reason to decide early is prompt architecture. If you know from the start that the same model will serve cutouts, scenes, and text layouts, you can build one small set of versioned prompt templates instead of ad-hoc prompts per request. That decision costs nothing up front and saves a rewrite later.

A working request: curl and Python

Before designing prompts, get one image back. The request shape on HiAPI is consistent across models: an API key, a model name, and your input parameters in the body. The minimal parameters you need for qwen-image-2.1-pro are the prompt, plus whatever input image you are editing if the task is an edit rather than a fresh generation.

curl

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "studio product photo of a matte black ceramic coffee mug, three-quarter view, soft diffused key light from the left, subtle reflection on a light grey seamless background, no text",
    "size": "1024x1024"
  }'

Python requests

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-2.1-pro",
        "prompt": "studio product photo of a matte black ceramic coffee mug, "
                  "three-quarter view, soft diffused key light from the left, "
                  "subtle reflection on a light grey seamless background, no text",
        "size": "1024x1024",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

Two habits worth forming at this stage. First, pull the API key from the environment, never hardcode it — you will be running this from a batch job soon enough. Second, keep the response body intact when you log it, including any usage fields the endpoint returns; that is what you will use later to measure cost per approved asset rather than guessing it.

Run the request once with a generic prompt like the one above. Confirm you get an image and that the response structure is what your downstream code expects. Only then move on to the recipes — prompt design is the slow part, and you do not want to discover a plumbing problem halfway through it.

Prompt recipes for transparent PNGs and product scenes

Ad-hoc prompts drift. A catalog team gets consistent results by keeping a small library of templates with explicit variable slots, versioning them in the repo alongside the code that calls the API, and swapping only the slots per SKU.

Recipe 1: transparent cutout

Product cutout of {product_name}, {distinguishing_detail}, isolated on a fully transparent background.
{view_angle} view, product centered and fully in frame with a small margin.
Soft even studio lighting, no hard shadows cast onto the background, subtle contact shadow directly beneath the product only.
Photorealistic, sharp edges, no text, no props, no background elements.

Slots: {product_name} ("a matte black ceramic coffee mug"), {distinguishing_detail} ("visible rim thickness and a small handle"), {view_angle} ("three-quarter", "front", "top-down"). Keep the transparency clause and the no-shadow-onto-background clause verbatim; those two lines do most of the work for cutouts.

Recipe 2: lifestyle scene

Lifestyle product photo of {product_name} in {scene_description}.
The product is the hero: sharp focus, correct proportions, {brand_color_note}.
{lighting_note}. Shallow depth of field with the background softly out of focus.
Natural, editorial style. No text, no logos, no visible brand marks on the background.

Slots: {scene_description} ("a bright minimal kitchen counter with a linen napkin and a morning window"), {brand_color_note} ("unmodified color, no tint applied"), {lighting_note} ("warm directional morning light from the right").

Recipe 3: studio hero

Studio product photo of {product_name}, {view_angle} view.
{background_description}. Key light from {key_light_direction}, soft fill, controlled reflection.
Photorealistic, high detail on material and surface finish. No text.

Two rules keep the library healthy. Never edit a template inline in a script — change the template file, bump its version, and regenerate. And record which recipe version produced each approved asset, so when a template changes you can tell whether old approvals still hold.

Editing existing product images

Edit requests are where most quality problems appear, because vague prompts let the model regenerate the product instead of modifying the scene around it. Structure every edit prompt in three explicit parts:

1. What to change — the scene, background, lighting, or added props.
2. What to preserve — the product's shape, proportions, label artwork, material, and color.
3. What to avoid — new text, new logos, warped geometry, duplicated parts.

A template that works:

Edit this product photo.
Change: replace the background with {new_background}; adjust the lighting to {new_lighting}.
Preserve: the product's exact shape, proportions, surface material, and any label artwork exactly as in the original.
Do not: add text, add logos, change the product's color, or alter its geometry.
Photorealistic result that looks like one continuous photograph.

Filled in: {new_background} = "a clean warm-grey seamless backdrop", {new_lighting} = "soft overhead diffused light with a gentle gradient behind the product".

Preservation clauses are not a guarantee. Long edits — a background swap plus a lighting change plus added props in one prompt — give the model more room to drift on the product itself. Split the work: do the background swap first, review it, then apply secondary changes in a follow-up edit against the approved intermediate. Each step is one comparison the reviewer can actually judge.

Also keep a canonical reference image per SKU. When a reviewer is unsure whether the product changed, the reference is the ground truth, not the previous generation.

Text rendering and layout control

On-image text is the feature most likely to disappoint if prompted casually. Words that must appear in the final asset need to be quoted, positioned, and constrained.

E-commerce banner for {product_name}.
Layout: product on the right third, text block on the left two-thirds, generous margins.
Text: render exactly "{headline}" as the headline in a bold sans-serif, and exactly "{subline}" beneath it in a lighter weight.
Style: {color_scheme}, clean and modern, high contrast for readability.
No other text anywhere in the image. Spell all words exactly as written.

Why each line matters:

• Quoted text with an explicit "exactly" instruction reduces paraphrase and invented words.
• Position and proportion ("right third", "left two-thirds") stop the model from burying the product under the headline.
• "No other text anywhere" is the clause that suppresses the common failure mode: plausible-looking filler text in corners.
• One short headline plus one short subline is far more reliable than a paragraph. If your layout needs a paragraph of copy, generate the image without it and typeset the copy in your CMS or design tool.

For badges and labels (a "New" tag, a size marker), treat them as their own small prompt rather than adding them to a hero shot — a short badge prompt with a single quoted word is much easier to verify at review than a full banner. Always check spelling at full resolution before approval; text errors are cheap to catch and expensive to ship.

Reviewing outputs: a compare-and-approve loop

Generated assets should not reach a storefront without a human pass. The cheapest reliable loop is a before/after comparison per asset: the input photo (or the spec, for fresh generations) next to the generated output, with the prompt recipe version and variable values recorded.

A workable loop for a small team:

1. Generate a small batch — a handful of variants per SKU, not the whole catalog.
2. Render a side-by-side sheet: source on the left, candidate on the right, prompt recorded below.
3. Review against a short fixed checklist: product shape unchanged, label artwork intact, background clean, text spelled correctly, margins adequate.
4. Mark each candidate approved or rejected, and record the recipe version that produced the approvals.
5. Only then fan out to the batch, reusing the approved recipe. If a recipe changes after approval, treat existing approvals as provisional until re-checked.

Keep the checklist short and identical every time. A four-item checklist applied consistently catches more than a long form applied unevenly. Store rejected candidates too — they are the evidence for why a recipe version was retired, and they save the next person from re-discovering the same failure.

This loop is also your cost control. Because approvals are tied to recipes, you can compute how many generations each approved asset required and iterate on the templates that burn the most attempts.

Cost, latency and batching considerations

Plan with your own measurements, not assumptions. For image models on HiAPI, billing is per output image, so the variable that dominates your spend is attempts per approved asset — which is entirely a function of prompt quality and review strictness. Current per-image pricing lives on the site's pricing page; do not bake numbers into your code or your budget docs.

A sensible working method:

• Measure the baseline. Run ten SKUs through your approved recipes, count total generations and total approvals, and derive attempts-per-approved-asset. That single ratio tells you more than any benchmark.
• Iterate on singles, batch on approvals. Prompt iteration should be one image at a time. Once a recipe is approved, run it in batch with modest concurrency and a retry policy that logs failures rather than silently re-billing.
• Treat latency as a scheduling parameter. Image generation takes seconds, not milliseconds. Kick off batch jobs asynchronously, write results to a queue, and let reviewers work through the queue rather than blocking on each call.
• Budget by ratio, not by unit. With attempts-per-approved-asset in hand, a catalog estimate is straightforward arithmetic against your own measured numbers.

One last piece of hygiene: version your recipes and log the recipe version with every request. It costs one field, and it turns "why did this asset look different last month?" from an investigation into a lookup.

Build the smallest pipeline that gets you a cutout, a scene, and a text layout through the API, keep the prompt library versioned, and let the review loop — not hope — decide what ships.