---
description: Clearcut generate a scene. Learn how to remove image backgrounds, manage jobs and work with credits in your application.
title: Generate a scene | Clearcut
image: https://clearcut.sh/og/docs.png
---

GUIDES

[Quick start](https://clearcut.sh/docs)[Authentication](https://clearcut.sh/docs/authentication)[Credits & billing](https://clearcut.sh/docs/credits)[Limits & retries](https://clearcut.sh/docs/limits)[Examples](https://clearcut.sh/docs/examples)[Errors](https://clearcut.sh/docs/errors)

API REFERENCE

[POSTRemove a background](https://clearcut.sh/docs/remove-background)[GETremove.bg account info](https://clearcut.sh/docs/removebg-account)[POSTCreate an image job](https://clearcut.sh/docs/create-job)[GETGet a job](https://clearcut.sh/docs/get-job)[GETList images](https://clearcut.sh/docs/list-jobs)[DELETEDelete an image](https://clearcut.sh/docs/delete-job)[GETDownload a result](https://clearcut.sh/docs/download)[POSTExport an edited image](https://clearcut.sh/docs/export)[POSTUpload a background](https://clearcut.sh/docs/background)[POSTExport a ZIP batch](https://clearcut.sh/docs/batch-export)[POSTCopy a batch background](https://clearcut.sh/docs/batch-background)[POSTSmart Brush](https://clearcut.sh/docs/smart-brush)[POSTGenerate a scene](https://clearcut.sh/docs/generate-scene)[GETCredit balance](https://clearcut.sh/docs/account)[POSTRetry a failed image](https://clearcut.sh/docs/retry-job)[GETRecent usage](https://clearcut.sh/docs/usage)[Download OpenAPI](https://clearcut.sh/openapi.json)

API reference / Generate a scene

# Generate a scene

Generate an empty background matched to the current subject by default. The original cutout remains a separate, movable layer. Apply suggested\_settings together with your placement settings when exporting to add the suggested contact shadow. Large placement changes may need a new scene. Optional AI operation, 3 credits per successful request. Failed operations refund credits. Reuse an Idempotency-Key for the same request; do not automatically retry with a new key.

POST`/api/jobs/{id}/generate`

Authenticate with `X-API-Key`. Keep your key on your server; never embed it in a public website.

## Request parameters

`match_subject`booleandefault: true

Match the scene to the cutout, placement and lighting. Set false for an independent backdrop.

`settings`object

Current export settings, including ratio, scale, position, rotation and color adjustments. Background, text and shadow are excluded from the reference. Used when matching.

`mask`string

Optional PNG or WebP mask as a base64 data URL, white to keep and black to erase. Used when matching; include the same mask when exporting.

`prompt`string

Describe the setting in 1–1,000 characters. Recommended. Omitting it uses the legacy style preset.

`background`string

Optional visual reference: a background belonging to this image or an included background. Omit for prompt-only generation.

`style`stringdefault: studio

Legacy preset, used only when prompt is omitted.

`studio` `nature` `city` `interior` `beach`

`seed`integer

Deprecated. Accepted for older clients but ignored by the scene generator; output is not seed-reproducible.

## Response

200 · Success

{
  "url": "/api/files/image_id/bg_background-id.png",
  "matched": true,
  "suggested_settings": {
    "shadow": 35,
    "shadowType": "ground"
  }
}

Errors use a structured `error.code` and `error.message`. [See error handling →](https://clearcut.sh/docs/errors)

## Example request

Replace IMAGE\_ID with your job ID. This example calls the endpoint shown here.

cURLPythonNode.js

```
curl https://clearcut.sh/api/jobs/IMAGE_ID/generate \
  -X POST -H "X-API-Key: $CLEARCUT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Warm beige photography studio, soft side lighting, seamless backdrop."}'
```

[More examples →](https://clearcut.sh/docs/examples)

Need help?

Prefer email? [support@clearcut.sh](mailto:support@clearcut.sh)

Generate a scene | Clearcut

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://clearcut.sh/#organization","name":"Clearcut","url":"https://clearcut.sh","logo":"https://clearcut.sh/apple-touch-icon.png","email":"support@clearcut.sh","description":"An independent image background removal service operated by chern0.dev.","contactPoint":{"@type":"ContactPoint","email":"support@clearcut.sh","contactType":"customer support"}},{"@type":"WebSite","@id":"https://clearcut.sh/#website","url":"https://clearcut.sh","name":"Clearcut","description":"Remove image backgrounds with Clearcut. Get 30 free credits every month for the website and API. Full-resolution downloads, no watermark. Packs from $3.","inLanguage":"en","publisher":{"@id":"https://clearcut.sh/#organization"}}]}
```