AI Rug Photography API — Colorway and Pattern Variants
A rug brand is launching one hand-tufted design in six colorways and three fringe styles: no fringe, short tassel, and knotted. That is eighteen combinations, and the studio has photographed exactly one: the sand colorway with no fringe, laid in a bright living room. Shooting the rest means moving furniture, unrolling and steaming each rug, and rebalancing the light for every variant. Generating the other seventeen from the one reference photo lets the product page and the retailer feed go live while the physical samples are still being woven.
Direct answer: a reference-guided image generation API takes one rug photo as image input plus a prompt describing the target colorway, pattern tone, or fringe style, and returns a new image that keeps the room, camera angle, and rug shape consistent while changing the requested elements.
How Does an API Generate Rug Variants From One Photo?
Reference-guided generation anchors the output to the composition of the source image, then applies the change described in the prompt. Reference-guided generation means the model receives an existing image as input alongside the text prompt, rather than starting from text alone. For rugs, that anchoring preserves the room layout, the rug outline, and the perspective of your real photo, where a text-only prompt would invent a generic rug that does not match your catalog.
Describe the change in visual terms ("rust-orange wool, same diamond pattern in cream") rather than an internal SKU code, which the model cannot map to a color or material.
Can the Generated Pattern Be Trusted as Accurate?
No, treat generated rug images as a visual placeholder, not a design reference. Repeating patterns are hard for image models to hold exactly: a diamond repeat can change count or spacing, border widths can drift, and pile texture can look flatter or deeper than the real product. Shoppers judge a rug largely by pattern and color, so errors there matter.
Two practical rules:
- Use generated images for the variant grid, internal review, and pre-order pages, then swap in real photography once samples exist.
- Compare each generated image with the physical sample, in daylight, before it reaches a customer-facing page.
Which Model Fits Rug Photography?
Nano Banana Pro's reference-guided mode holds the room and rug outline consistent across colorway and fringe changes, which matters when shoppers compare variants side by side. GPT-image-2 suits instruction-based touch-ups on an image that is otherwise final, such as removing a stray cable or swapping the wall color behind the rug.
| Model | Mode | Resolution / price | Composition consistency | Best for |
|---|---|---|---|---|
| Nano Banana Pro | Reference-guided | 1K $0.030 / 2K $0.030 / 4K $0.042 | High | Full colorway sets from one studio room shot |
| Nano Banana 2 | Reference-guided | 1K $0.020 / 4K $0.036 | Medium-high | Lower-cost drafts for internal review |
| GPT-image-2 | Instruction-based edit | $0.014/image | N/A (edits existing photo) | Small touch-ups on a near-final shot |
Nano Banana Pro at 2K costs the same $0.030 as 1K, so a retail-facing set gains resolution at no extra cost.
How Do I Generate a Colorway Variant via API?
Submit the base photo as image input with a prompt describing the target color and fringe; the endpoint returns a job ID to poll for the finished image.
import requests, time
API_KEY = "YOUR_KEY"
BASE = "https://genrelay.ai/v1"
def generate_variant(reference_url, colorway, fringe):
r = requests.post(
f"{BASE}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"model": "nano-banana-pro",
"prompt": f"same living room, rug outline and camera angle, "
f"{colorway} hand-tufted wool rug, {fringe}, "
f"soft daylight, studio product shot",
"image": reference_url,
"resolution": "2k",
},
)
return r.json()["id"]
job_id = generate_variant(
"https://cdn.example.com/rug-sand-nofringe.jpg",
"rust-orange with cream diamond pattern",
"short tassel fringe on the short edges",
)
Reference-guided generation is asynchronous, so poll the job until it completes:
def wait_for_result(job_id, timeout=90):
start = time.time()
while time.time() - start < timeout:
status = requests.get(
f"{BASE}/images/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
).json()
if status["status"] == "completed":
return status["output_url"]
if status["status"] == "failed":
raise RuntimeError(status.get("error"))
time.sleep(2)
raise TimeoutError(f"Job {job_id} did not finish in {timeout}s")
image_url = wait_for_result(job_id)
How Do I Batch a Full Colorway Range?
Loop over the colorway and fringe list and submit each as its own job. The batch image generation guide covers the concurrency and retry pattern this scales to.
combos = [
("sand with cream diamonds", "no fringe"),
("slate blue with cream diamonds", "short tassel fringe"),
("rust-orange with cream diamonds", "knotted fringe"),
("forest green with cream diamonds", "no fringe"),
]
jobs = [(c, f, generate_variant(reference_url, c, f)) for c, f in combos]
for colorway, fringe, job in jobs:
print(f"{colorway} / {fringe}: {wait_for_result(job)}")
What Does a Full Variant Set Cost?
Eighteen combinations (6 colorways × 3 fringe styles) at 2K on Nano Banana Pro cost 18 × $0.030 = $0.54. A brand adding a close-up of the pile for each of the 6 colorways (6 more images) pays 24 × $0.030 = $0.72 in total.
| Launch size | Images | Model | Cost |
|---|---|---|---|
| 6 colorways × 3 fringe styles | 18 | Nano Banana Pro, 2K | $0.54 |
| Plus pile close-up per colorway | 24 | Nano Banana Pro, 2K | $0.72 |
| Internal review pass | 6 | Nano Banana 2, 1K | $0.12 |
Running the internal review on Nano Banana 2 first keeps early decisions inexpensive, and approved variants then move to Nano Banana Pro. Once stills are approved, the same photos can feed the rug showcase video guide for pile-pan and light-shift clips.
FAQ
Can the API change the rug color without changing the room?
Yes. Describe the target colorway and state that the room, rug outline, and camera angle stay the same; the reference image keeps the composition anchored.
Will the model reproduce a detailed pattern or a woven label exactly?
Not reliably. Fine repeats and small labels often blur or shift. Generate the colorway and composite real label artwork afterward.
Can I use the output for a retailer listing?
That is a decision for your own brand and retailer guidelines. Many retailers require images to match the shipped item, so verify each variant against the real product before publishing.
How long does a generation take?
Jobs are asynchronous. The polling loop above uses a 90-second timeout, which is a conservative ceiling rather than a typical time.
Can I generate matching clips from the same photos?
Yes. The rug video guide shows how to animate each variant into a short pan and light-shift clip.
See the Nano Banana Pro model page for parameter docs.