Blog

Guide

Using gpt-image-2.5-sunburst/image-to-image for E-commerce Product Images via the HiAPI API

Reference images, background swaps, lifestyle scenes, and a working HiAPI request

Nov 20, 2026 13 min read
Minimal cover art of mint-green dots on near-black, denser to the right like a halftone dataset, for the e-commerce product image guide.
On this page

Why image-to-image suits e-commerce product photos

Text-to-image is great at inventing products that don't exist. That is almost never what a catalog team needs. You already have the physical product, the packaging, the label, and the colorway — what you lack is time and budget to shoot every SKU against every background and in every lifestyle context.

gpt-image-2.5-sunburst/image-to-image takes an existing photo as its anchor and applies an edit instruction to it. That changes the economics of product imagery in a few concrete ways:

  • Fidelity to the real item. The input image carries shape, material, color, and label layout. The model's job is to preserve those while changing what you asked it to change, rather than re-imagining an approximate product.
  • Cheaper iteration. A new background or scene is a prompt change, not a studio booking. You can test several lifestyle directions for one SKU in an afternoon and keep the winner.
  • Consistency across a set. Because every output derives from a comparable source photo, a batch of edits keeps a family resemblance that fresh generations rarely do.

When to reach for it — and when not to

Reach for image-to-image when the product itself is fixed and the context is variable: background swaps for marketplace listings, lifestyle scenes for ads and landing pages, seasonal reskins, or localized props. It is also a reasonable tool for cleaning up a decent-but-imperfect shot.

Do not reach for it when you are generating a concept that never existed, when the source photo is unusable (badly out of focus, product mostly occluded), or when you need exact label copy reproduced at print fidelity. In those cases a reshoot or a vector asset beats any model.

One practical framing: treat the source photo as ground truth and the prompt as a scoped instruction. Every edit you write should answer the question, "what am I keeping, and what am I changing?" Requests that leave that ambiguous are where quality falls apart.

The endpoint you call is the same one described on the model page; the rest of this guide is about how to feed it well.

Preparing reference images that survive the edit

The model can only preserve what it can see. Most disappointing product edits trace back to the input photo, not the prompt. Before you send anything, run the source through a short checklist.

Resolution and sharpness

Send the largest clean version you have. Downscaled thumbnails lose the fine structure the model needs to hold onto — stitching, texture, small typography. If the image is soft or motion-blurred, fix or reshoot it first; sharpening filters in a pre-step rarely help, and can introduce halos the model then amplifies.

Framing and breathing room

Give the product padding around its edges. If the item touches the frame, the model has nowhere to build a new background and tends to crop or warp the subject. A single-product shot with clear margin on all four sides edits far more reliably than a tight crop, and it gives you room to reposition within the new scene.

Subject isolation

You do not need a pixel-perfect cutout, but a clean separation between product and backdrop does most of the work. A consistent, low-detail background (seamless paper, a neutral sweep, plain wall) is enough. Busy backdrops compete with your instruction and leak into the output.

Lighting and perspective

Shoot or select a source whose light direction you are happy to keep, because the edit will try to match it. A product lit from the front-left will want a key light from the front-left in the new scene. Also keep a consistent camera angle per category — a top-down flat lay and a three-quarter hero shot in the same product row will never look coherent.

Labels, logos, and type

If the product has text the customer must read, check that it is legible in the source. The model will do its best to carry it through, but small or angled text degrades first. For regulated or brand-critical copy, plan a human review pass, and consider keeping the text-bearing face toward the camera.

A note on batching

When preparing many SKUs, normalize them: same crop ratios, same padding, same background tone. The effort you spend at this stage shows up directly as consistency in the outputs, and it makes prompt reuse safe across a whole category.

Swapping product backgrounds cleanly

Background replacement is the most common e-commerce edit and the easiest place to get lazy prompting. "New background" is not an instruction — it is a wish. The model needs to know what the new space looks like and how the product should sit in it.

Describe the space, not just the word

Name the surface, the backdrop, and the light. "Product on a matte white surface with a soft gradient backdrop, large diffused key light from upper left, gentle contact shadow beneath the product" gives the model a scene to build. "White background" gives it permission to guess.

Keep the product clause explicit

Every background prompt should carry a preservation clause: keep the product's shape, proportions, colors, materials, and label text unchanged. This is cheap to write and measurably reduces drift, especially on items with distinctive silhouettes.

Protect edges and shadows

Clean cutouts come from prompts that mention contact and shading. Ask for a natural contact shadow where the product meets the surface, and for edges that stay crisp against the new backdrop. If you are replacing a dark backdrop with a light one, expect the model to need help on rim lighting — say that the product's edge is lit consistently with the new environment.

Matching the product's own light

If the source was shot with a single softbox, do not ask for dramatic hard-light studio staging. Mismatched lighting is the giveaway that a listing is composited. Describe lighting that is plausible for the source, and instead vary the backdrop color and surface texture to get visual variety.

Marketplace constraints

If the destination requires a pure white or flat-color field, say so plainly and ask for no props and no visible surface seam. If the destination is a branded storefront, you have more latitude — gradients, subtle texture, and a matching floor plane are all fair game.

Iterate one variable at a time

Change the backdrop first, confirm the product survived, then adjust shadow or lighting. Changing several things in one prompt makes it impossible to tell which clause caused a failure, and every failed request still costs you output.

Placing products in lifestyle scenes

Lifestyle scenes are where image-to-image earns its keep: the product stays recognizably itself while the world around it changes. The craft here is scale, light, and plausibility.

Anchor the scene with a few concrete details

A scene prompt needs enough specificity to constrain composition without dictating every pixel. Specify the setting, the surface the product rests on, one or two supporting props, and the quality of light. "On a weathered oak kitchen counter, morning light through a window on the right, a ceramic mug and folded linen just out of focus behind" is workable. A long inventory of props is not — it competes with the product for the model's attention.

Get scale right

State the product's real-world size relationship, because the model has no ruler. A tall bottle and a small lip balm both look plausible alone and absurd together. Mentioning the surface and a recognizable reference prop (a hand, a standard mug, a shelf) keeps scale anchored.

Match light to the source, then to the scene

You are solving two light problems at once: the product's existing shading and the new environment's lighting. If the source light is diffuse and even, choose scenes with soft daylight rather than hard sunset rim light. Write the light direction explicitly and say the product's lighting should be consistent with the scene. When they conflict, expect either a relit product that no longer matches your other shots, or a pasted-in look.

Keep the product in focus and the scene secondary

Say that the product is the sharp subject and the environment falls off slightly out of focus. This single clause does more for realism than any prop list, and it stops the model from inventing hero detail in the background.

Vary the scene, not the product

For a category page, hold the scene template constant and vary one element — season, surface, prop — across SKUs. Shared scene grammar is what makes a grid of lifestyle images read as one campaign instead of a stock-photo collage.

One isolated product dot-cluster branches into three lifestyle contexts at matched density and scale.

A working HiAPI image-to-image request

Everything goes through one authenticated endpoint, so the request shape stays the same regardless of what you are editing. The essentials are the model ID, your source image, and the prompt.

The request

curl -X POST "https://api.hiapi.ai/v1/images/edits" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/products/sku-1042-source.jpg",
    "prompt": "Keep the product shape, proportions, colors, materials, and label text unchanged. Replace the background with a matte warm-grey surface and soft gradient backdrop, large diffused key light from upper left, natural contact shadow beneath the product, crisp product edges, product remains the sharp subject.",
    "size": "1024x1024",
    "n": 1
  }'

The image field accepts a hosted URL or a base64 data payload if your assets are not publicly reachable — base64 keeps pre-launch SKUs off a public CDN. Keep n at 1 while you are iterating; multiple candidates multiply cost and make it harder to attribute quality changes to a prompt edit.

Reading the response

The API returns a JSON body with a data array; each element carries the resulting image (as base64 or a URL, depending on your account settings). Check the response's created timestamp and any usage fields your response includes, and log them next to the request ID so you can reconcile later.

A minimal Python call looks like this:

import os, requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-sunburst/image-to-image",
        "image": source_url,
        "prompt": prompt,
        "size": "1024x1024",
        "n": 1,
    },
    timeout=180,
)
resp.raise_for_status()
item = resp.json()["data"][0]

Practical wiring notes

  • Store the prompt alongside every output. Weeks later, the winning image is only reproducible if you kept the exact prompt and source.
  • Handle transport failures separately from model failures. Timeouts and 5xx responses are retryable; a request rejected for an unsupported size is not.
  • Download and persist outputs immediately rather than relying on temporary URLs.
  • Keep the model string in configuration, not scattered through code, so a future model swap is a one-line change.

The endpoint reference and supported parameters live on the model page; billing there is metered by output, so trimming failed iterations is the main lever on spend.

Two inputs — a source image dot-field and a prompt trace — pass through one API conduit and resolve into a refined output field.

Handling artifacts and keeping output consistent

Even with good inputs and careful prompts, product edits fail in recognizable ways. Each failure mode has a standard fix.

Product shape drift

Symptom: the silhouette changes slightly — a handle thickens, a taper straightens. Cause: the prompt describes the scene more than the product, so the model reinterprets the subject. Fix: lead with the preservation clause, name the shape explicitly, and simplify the scene description. If drift persists, the source framing is probably too tight.

Lost or mangled label text

Symptom: brand names turn into plausible-looking glyph soup. Cause: small, angled, or low-contrast text in the source. Fix: start from a sharper, more front-facing source; state that label text and logo remain unchanged and legible; avoid adding heavy background detail behind the label area. For regulated copy, plan human review regardless.

Inconsistent framing across a set

Symptom: each image in a category sits at a different scale and angle. Cause: inconsistent source crops and per-image prompts. Fix: normalize source padding and camera angle before editing, and reuse one prompt template across the batch, changing only the scene variables.

Edge halos and floating products

Symptom: a light rim around the product or a shadowless object that looks pasted in. Cause: light mismatch between source and requested scene. Fix: request a natural contact shadow explicitly, state the light direction, and pick environments whose lighting matches the source shot.

Over-edited, plastic look

Symptom: textures smoothed away, fabric too clean. Cause: prompts asking for "polished" or "professional" without restraining retouching. Fix: ask for the original texture, material grain, and wear to be preserved.

The general rule

One variable per iteration, one preservation clause per prompt, and a fixed source-photo standard. When an output fails, first ask whether the input photo was good enough — most of the time the answer is no.

Fitting image edits into a catalog workflow

A working single request is not a pipeline. Turning this into catalog-scale output is mostly engineering discipline around the model call.

Normalize inputs at ingest

Build a small pre-processing step that crops to a standard ratio, adds fixed padding, and flags low-resolution or blurry sources before they ever reach the API. A pre-flight check that rejects bad inputs saves more spend than any prompt tuning.

Batch by template, not by SKU

Group products into categories and give each category one or two prompt templates. Run the batch, then review a contact sheet per template. Changing a template and re-running the category is far cheaper than hand-authoring prompts per item, and it keeps the visual grammar consistent.

Review in two passes

First pass is a fast reject: does the product look like itself, is the text readable, are the edges clean? Second pass is a design review against your brand guidelines. Automate the mechanical checks where you can — image hashing against the source for gross drift, resolution and format validation for delivery.

Keep provenance attached

Store source image, prompt, model ID, and timestamp with every output. When a product manager asks why one hero image looks different, the answer should be a diff of two prompt records, not an investigation.

Stage the rollout

Start with background swaps, which are the lowest-risk edit, and move to lifestyle scenes once your templates are stable. Roll out to one category before the whole catalog, and keep the ability to regenerate any single item on demand.

Know where the model stops

The pipeline does not remove the need for a photographer on flagship SKUs, nor does it replace legal review of product claims. Treat generated edits as one production tier, and reserve the studio budget for the images where fidelity is the product.

If you are ready to test it against your own catalog, the request shape above is all you need to start with gpt-image-2.5-sunburst/image-to-image on HiAPI.

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