Car Layers (Base64)#

Endpoint#

POST /v1.0/car-layers-base64

Base URL: https://api.withoutbg.com · Spec: openapi.json

Example (cURL)#

curl -X POST \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_base64":"<raw_base64>","scene_overrides":{"albedo":[0.92,0.9,0.86],"floor_albedo_scale":0.5}}' \
  "https://api.withoutbg.com/v1.0/car-layers-base64"

Authentication#

Provide your API key in the request header:

X-API-Key: <your_api_key>

Request#

Content-Type: application/json

Fields#

• image_base64 (string, required) — Input image as a raw Base64 string (no data: URI prefix). Supported formats: JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF. Maximum decoded size: 20.0 MB. Invalid Base64, non-image data, unsupported formats, or oversize payloads fail with HTTP 422.
• background_preset (string, optional) · default "white-seamless" — Backdrop the car is composited onto. Rendered procedurally in the photo's recovered camera, so perspective matches. Fine-tune it with scene_overrides. Previews: https://withoutbg.com/docs/pro-model/car-layers-base64#background_preset

  

  

  

  

  

  

• scene_overrides (object, optional) — Optional tweaks on top of background_preset; omitted fields keep the preset's value. Unknown keys are rejected. Each field applies only to the preset families in its x-backgroundFamilies (today every field is indoor-only); a field that doesn't apply to the chosen preset is rejected. Examples: https://withoutbg.com/docs/pro-model/car-layers-base64#scene_overrides

  

  

  {
    "scene_overrides": {
      "albedo": [
        0.92,
        0.9,
        0.86
      ],
      "floor_albedo_scale": 0.5
    }
  }

• scene_overrides.albedo ([number, number, number], optional, 0–1) — Backdrop colour as linear RGB, each 0–1, e.g. [0.92, 0.90, 0.86] for a warm off-white.
• scene_overrides.floor_albedo_scale (number, optional, 0–2) — Floor brightness relative to the wall: 1 = same as wall, 0.12 = graphite floor under a white wall (as graphite-floor).
• scene_overrides.bevel (number, optional, 0–1) — Wall-to-floor transition: 0 = hard corner, 1 = smooth cove.
• scene_overrides.pool_gain (number, optional, 0–1) — Strength of the light pool on the floor under the car: 0 = flat, 0.9 = spotlit (as dark-hero).
• scene_overrides.pool_radius_m (number, optional, 0.5–10) — Radius of the light pool in metres (presets use 2.2–4.5).
• scene_overrides.exposure (number, optional, 0.25–4) — Backdrop brightness multiplier: 1 = preset, 0.8 = darker, 1.2 = brighter.
• frame (boolean, optional) · default true — When true (default), reframe the output: the car fills about 60% of the frame width with headroom above and floor below, its shadow kept in frame. When false, the output keeps the photo's framing and size.
• frame_aspect (string, optional) · default "4:3" — Output aspect ratio (width:height) when frame is true. original keeps the photo's own ratio. Ignored when frame is false. Shapes: https://withoutbg.com/docs/pro-model/car-layers-base64#frame_aspect
  4:3

  4:3default

  Landscape, the marketplace listing default.

  3:2

  3:2

  Landscape, matches most DSLR photos.

  16:9

  16:9

  Wide banner or website hero.

  1:1

  1:1

  Square, for social posts and thumbnails.

  photo's ratio

  original

  Keep the photo's own width:height ratio.

• frame_grow (boolean, optional) · default true — When true (default) and the ideal frame reaches past the photo's edge, extend the rendered backdrop instead of cropping tighter. When false, the frame stays inside the photo: it keeps frame_aspect and may trim the car's front and rear when the car fills the photo.
• match_photo_light (boolean, optional) · default true — When true (default), detect the car's existing shadow in the photo and fit the light direction to it, so the new shadow falls the same way. Falls back to the default light when no usable shadow is found.
• reconstruct_windows (boolean, optional) · default true — When true (default), run car window reconstruction: opens glass interiors while keeping the car outline. Set false to skip and use the base silhouette alpha only.
• outputs (array<string>, optional) · default ["composite","cutout"] — Which layers to return: composite (car + shadow + backdrop), cutout (car alone, optionally with shadow), shadow (soft cast-shadow mask), background (empty backdrop). Default returns the composite and cutout. Omitted layers reduce API latency and data transfer. Examples: https://withoutbg.com/docs/pro-model/car-layers-base64#layers
  Values:compositecutoutshadowbackground
• bake_shadow (boolean, optional) · default true — When true (default), the cutout includes the camera-grounded cast shadow. When false, the cutout is the car alone (fused alpha over the original RGB).
• output_format (string, optional) · default "jpeg" — Image format for composite and background: jpeg (default, smaller), png (lossless), or webp (modern). cutout and shadow are always PNG.
  Values:jpegpngwebp
• max_size (integer, optional, 256–8192) — Resize all output layers to fit within this longest side (pixels), 256–8192. Null (default) keeps the processed size. Resizing happens after compositing, so frame metadata stays valid.

Response#

Success Content-Type: application/json

Body fields#

• input_dimensions (array<integer>, required) — Decoded input size as [width, height] (pixels).
• processed_dimensions (array<integer>, required) — Size after server prep downscale (longest-side / megapixel caps) as [width, height]. Distinct from model inference resolution (~1024 long side).
• was_downscaled (boolean, required) — True when the input was downscaled during server prep.
• composite_base64 (string, optional) — The car and its cast shadow on the rendered backdrop, as Base64 (JPEG, PNG, or WebP per output_format). Prepend data:image/jpeg;base64, or appropriate MIME type to display in a browser.
• img_without_background_base64 (string, optional) — Car as Base64 PNG (RGBA). When bake_shadow is true, the cast shadow is baked in; when false, the car alone. Same frame as composite_base64. Prepend data:image/png;base64, to display in a browser.
• shadow_base64 (string, optional) — Soft cast-shadow mask as Base64 grayscale PNG (L mode; 0 = no shadow, 255 = full shadow). Same dimensions as the output frame. Prepend data:image/png;base64, to display in a browser.
• background_base64 (string, optional) — Empty rendered backdrop, as Base64 (JPEG, PNG, or WebP per output_format). Same frame and size as composite_base64. Prepend data:image/jpeg;base64, or appropriate MIME type to display in a browser.
• output_dimensions (array<integer>, required) — Size of all output layers as [width, height], after any max_size resize. frame.box_xyxy and canvas_size are in unresized canvas coordinates.
• output_format (string, required) — Echo of the requested output_format.
  Values:jpegpngwebp
• frame (object, optional) — Output frame placement. Omitted when frame is false.
• frame.aspect (number, required) — Output width / height.
• frame.box_xyxy (array<integer>, required) — Output frame as [x0, y0, x1, y1] (exclusive end) on the render canvas; the canvas origin is the processed photo's top-left, shifted by any backdrop extension on the left/top.
• frame.canvas_size (array<integer>, required) — Render canvas as [width, height]: the processed photo's size, or larger when the backdrop was extended (grown).
• frame.grown (boolean, required) — True when the backdrop was extended past the photo's edges to fit the frame.
• background (object, required) — The backdrop the car was placed on.
• background.preset (string, required) — Preset that was rendered. Today the requested background_preset; read it from here, not from the request. More values may be added; don't fail on one you don't know.
  • white-seamless — Infinite white sweep, almost no direction.
  • grey-sweep — Neutral grey cyc with a shaped pool, the catalogue look.
  • graphite — Dark grey room, pool carries the separation.
  • graphite-floor — White wall over a graphite grey floor.
  • warm-showroom — Warm walls over a darker floor.
  • dark-hero — Near-black room with a tight pool under the car.
• background.family (string, required) — Scene family of preset. More values may be added; don't fail on one you don't know.
  • indoor — Studio backdrop: wall, floor and cove, lit by a studio rig.
• light (object, required) — Light the cast shadow was rendered with.
• light.azimuth_deg (number, required) — Light azimuth around the car, in degrees.
• light.elevation_deg (number, required) — Light elevation above the ground, in degrees.
• light.softness (number, required, 0–1) — How soft the light is, 0–1: 0 = hard light with crisp shadow edges (direct sun), 1 = very soft light with diffuse edges (overcast sky, large softbox).
• camera (object, required) — Where the photo was taken from, recovered from the photo itself.
• camera.elevation_deg (number, required) — Camera height as an angle seen from the car, in degrees: 0 = at ground level, 90 = straight overhead. Measured from where the car meets the ground, so a closer camera at the same height reads higher.

Errors#

Related endpoints#

• Car Background Removal (Binary) — POST /v1.0/car-image-without-background
• Car Background (Binary) — POST /v1.0/car-background