Background changer API

Product background changer API

Keep the model and the outfit exactly as they are and put them somewhere else: a studio color, a hotel lobby, a Paris street or a marble surface. The light on the subject is matched to the new place, in one request per photo.

Test keys are free and need no pack.

  • 17 ready scenes, a description in words, or a photo of your own place.
  • Several scenes in one request: one image per scene.
  • Square, 4:5 or 9:16: the scene is extended so nothing is cut off.
Model in a sand linen shirt and wide linen trousers in a plain studio
Input
The same model and outfit on a Mediterranean beach
coast
The same model in a whitewashed Greek island lane
description
POST https://api.garmo.studio/v1/edit/background
{
  "scenes": [
    "coast"
  ],
  "description": "a whitewashed Greek island lane with a blue door",
  "format": "same"
}

One request

Every request is asynchronous: the request returns a job in about two seconds, the images follow in 20 to 90 seconds by webhook or by polling.

curl https://api.garmo.studio/v1/edit/background \
  -H "Authorization: Bearer $GARMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://shop.example/products/linen-set-12.jpg",
    "scenes": [
      "coast"
    ],
    "description": "a whitewashed Greek island lane with a blue door",
    "format": "same"
  }'
Finished job · GET /jobs/{id}
{
  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
  "object": "job",
  "tool": "background",
  "status": "completed",
  "livemode": true,
  "outputs": [
    {
      "id": "out_1",
      "status": "succeeded",
      "label": "Your scene",
      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…0.webp?X-Amz-Signature=…",
      "url_expires_at": "2026-11-20T14:00:00Z"
    },
    {
      "id": "out_2",
      "status": "succeeded",
      "label": "Coast at sunset",
      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…1.webp?X-Amz-Signature=…",
      "url_expires_at": "2026-11-20T14:00:00Z"
    }
  ],
  "credits_charged": 2,
  "credits_refunded": 0,
  "metadata": {
    "sku": "DR-123"
  },
  "created_at": "2026-11-19T14:02:11Z",
  "completed_at": "2026-11-19T14:02:58Z"
}

Parameters

scenesScene ids from GET /catalog/scenes.
descriptionYour own scene in words (up to 300 characters).
scene_image_urlA photo of the place to use as the new background (or scene_image_base64, scene_image_upload_id).
formatShape of the result; the scene is extended so nothing of the subject is cut off.
Full reference

Cost

1 credit per scene

1 API credit = 1 image. Failed and canceled images are refunded automatically.

API pricing

What people build with it

One shoot, many places

Studio shots for the product page and lifestyle shots for ads from the same photo.

Seasonal refresh

Move the whole catalog to a summer terrace without a new shoot.

Channel formats

4:5 for the feed and 9:16 for stories from one portrait photo.

Prefer to click? Use it in Garmo Studio →

Good to know

Questions, answered.

What developers ask before connecting Garmo to a shop or a workflow.

Still stuck? Email us

Does the product change?

No. The prompt behind the endpoint keeps the subject exactly, with every detail and edge, and only replaces what is behind it and the light on it.

Can I use my own location?

Yes. Send scene_image_url with a photo of the place, or describe it in up to 300 characters.

What does it cost?

One credit per scene: three scenes on one photo make three images and cost three credits.

Other edits in the API

Get an API key

Test keys are free and need no pack.