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_subjectbooleandefault: true

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

settingsobject

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

maskstring

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.

promptstring

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

backgroundstring

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

stylestringdefault: studio

Legacy preset, used only when prompt is omitted.

studionaturecityinteriorbeach

seedinteger

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 →