Short answer. Send the source image and an instruction to
POST /v1/images/edits. Plugsky uses FLUX Kontext and returns the edited image URL. An edit costs 3 credits, so $0.12 per edit on Hobby, Starter and Builder at list price, or $0.072 on Scale. Generation is a different job: usePOST /v1/images/generationswhen the product does not have to survive pixel-for-pixel.
Edit versus generate
An edit starts from a real asset and preserves most of it. A generation starts from text and invents everything. Catalog teams get into trouble when they use generation for a job that needs the actual product, then discover the label, stitching or proportions drifted.
| Job | Endpoint | What must survive | Use when |
|---|---|---|---|
| Background swap | /v1/images/edits | Product, label, shadow | The SKU is fixed and the set changes |
| Outpainting | /v1/images/edits | Product, perspective | You need a wider crop for a banner |
| Object removal | /v1/images/edits | Everything except the object | A prop or hand is in the shot |
| New lifestyle scene | /v1/images/generations | Brand look, not exact SKU | Concept art, moodboards, UGC-style ads |
Editing is the safer default for a catalog; generation is for concepts and scenes where a slightly different product is acceptable. See image generation for that endpoint.
Edit modes: inpainting, outpainting and background swap
Inpainting. The documented Plugsky request is an image plus a prompt; there is no separate mask field. FLUX Kontext follows the instruction and keeps the rest of the frame. That is usually enough for “remove the price tag” or “repair the scuff on the left edge”, but it is guidance, not a hard matte. If a pixel region must not change, composite the result back through your own alpha mask and compare the untouched area.
Outpainting. Ask for the extension you want and state the new aspect ratio in words. The upstream model tries to match the input dimensions, so it is often more reliable to pad the source canvas first, send the padded image, and crop after the edit. Test the output dimensions before you build a layout around them.
Background swap. This is the highest-volume catalog job and the easiest to QA. Keep the product and its contact shadow fixed, name the new surface and light direction, and reject any result where the shadow does not match the new floor.
Before/after examples
| Before | Instruction | Pass criteria |
|---|---|---|
| White-background bottle, hard shadow | “Warm sand backdrop, soft shadow to the right” | Label unchanged; shadow direction matches light |
| Model holding a bag, cluttered street | “Clean studio background, keep the bag and hand” | Bag logo and strap unchanged; no extra fingers |
| Cropped shoe, cut at the toe | “Extend the canvas to a 4:5 portrait, keep the shoe” | Toe reconstructed; stitching pattern continues |
Reference-image limits
| Layer | Documented input | Practical limit |
|---|---|---|
| Plugsky edit endpoint | One image (PNG, JPEG or WebP) plus prompt | Treat one image as the contract; multi-reference is not documented |
| FLUX Kontext upstream | One primary image; up to three experimental reference slots | 20 MB or 20 megapixels per image |
| OpenAI GPT-image comparison | Up to 16 images; mask must match the first image | Useful benchmark for what a mature edit API exposes |
Do not promise a client “up to ten references” because another provider supports it. The safe product contract is one source image, one instruction.
Product-label drift checks
Label drift is the failure that gets a catalog rejected. The model can redraw a word, change a number, or invent a certification badge. Treat the label as a controlled field, not part of the creative surface.
- OCR before and after. Run plugsky-vision-fast or
plugsky-parseon the label crop and compare normalized text. - Check the numbers. SKU, size, weight, ingredients, dosage and regulatory statements must match exactly.
- Check the mark. Compare the logo crop against the approved asset with a perceptual hash, not a pixel diff.
- Check the geometry. A label that moved two centimetres or changed perspective is a reject even if the text is correct.
- Record the decision. Store the prompt version, source hash, output hash and reviewer.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_PLUGSKY_KEY",
base_url="https://api.plugsky.com/v1",
)
edit = client.images.edit(
model="dall-e-3", # alias; edits run on FLUX Kontext
image=open("sku-1042.png", "rb"),
prompt=(
"Replace the background with a warm sand studio backdrop. "
"Keep the product, label text, logo and contact shadow unchanged. "
"Soft window light from the left, 50mm product-photography look."
),
)
print(edit.data[0].url)
The prompt names what changes and what must not; “improve the background” is not testable.
Batch workflow and cost per edit
A batch is not a loop around the single-edit call. It needs a manifest, a stable source hash and a QA gate.
| Stage | Record | Failure action |
|---|---|---|
| Select | SKU, source URL, source SHA-256 | Skip duplicates and missing assets |
| Prepare | Canvas size, crop, colour profile | Reject images below the minimum crop |
| Edit | Prompt version, model, credit cost | Retry once on 5xx; never retry a content rejection |
| QA | Label OCR diff, logo hash, shadow check | Route to human review, not auto-publish |
| Publish | Output hash, reviewer, timestamp | Keep the original for rollback |
Run five SKUs end to end before a thousand. For campaign assets that pair edited stills with video, see the AI UGC ads guide.
| Plan | Credits / month | List $ / credit | Cost per edit (3 credits) | Cost per schnell image (1 credit) |
|---|---|---|---|---|
| Hobby $8 | 200 | $0.040 | $0.120 | $0.040 |
| Starter $20 | 500 | $0.040 | $0.120 | $0.040 |
| Builder $60 | 1,500 | $0.040 | $0.120 | $0.040 |
| Scale $120 | 5,000 | $0.024 | $0.072 | $0.024 |
These are list-price effective rates before top-ups. Credits are monthly, and unused credits do not roll over unless the plan says so. The real cost per published asset also includes the review minute: if 10% of edits need four minutes of human QA, that labour usually costs more than the credit. See pricing for current terms.
Limitations to design around.
- Editing is paid-only; the free plan excludes it.
- Text rendering is not guaranteed. Never let the model write a regulated claim.
- Prompt-based edits are guidance, not a pixel mask. Composite when isolation matters.
- Output dimensions may follow the input. Verify before you build a fixed layout.
- Review outputs for brand, copyright and likeness before publication.
FAQ
Does the image editing API support masks?
The documented Plugsky edit endpoint accepts an image and a prompt, not a separate mask. FLUX Kontext uses the instruction to scope the change. If you need hard pixel isolation, apply your own alpha mask to the result before publishing.
How many reference images can one edit take?
Plugsky documents one image plus a prompt. The upstream FLUX Kontext API exposes one primary image and up to three experimental reference slots. Do not build a product around reference slots you have not verified through Plugsky.
How much does one edit cost?
An edit costs 3 credits. At Hobby, Starter and Builder the effective price is $0.12 per edit at list price; at Scale it is $0.072. Top-ups and unused credits change the effective rate.
Can the API change text on a product label?
It can attempt a label change, but text rendering is not guaranteed. Run OCR on the before and after images and reject any edit that changes a SKU, size, ingredient or regulatory statement.
Is image editing available on the free plan?
No. Image generation and editing are paid-only. Hobby includes 200 credits per month; an edit consumes 3.
Sources
OpenAI image edit reference, checked 20 November 2026: developers.openai.com/api/reference. Black Forest Labs FLUX Kontext editing guide, checked 20 November 2026: docs.bfl.ai/kontext.
Reviewed 20 November 2026. Endpoint behaviour and credits were checked against the Plugsky documentation on that date. Generated and edited images need brand, copyright and likeness review before publication.