Car Background AI API

The Car Background AI API replaces the background of a car photo with one of the pre-built scenes, returning a high-resolution result image, and hides license plates.

All endpoints are authenticated with a workspace-scoped API key. Generations consume one credit per successful call from the workspace's balance.

Add your logo to generations with the logo option: upload up to seven logos once with POST /v1/logos (the same logos as in the app) or pass them inline per request. Pass a list to draw up to seven logos on one photo.

POST /v1/plates hides license plates without changing the background. It is included with any active subscription (no credits), up to a fair-use limit of 2,000 photos per workspace per month.

AI agents can use the same features through the MCP server at https://api.carbackground.ai/mcp (sign in with OAuth, or send an API key as the Bearer token). See https://api.carbackground.ai/llms.txt.

Rate limit: 80 requests/second per key, surfaced via X-RateLimit-* headers; a 429 includes Retry-After.

Contents

Operations

Schemas

Servers

Authentication

Tags

v1

Operations

Generate a background-replaced image

Submit a car photo (by URL or inline base64) and receive an image with the chosen background applied. The response returns only once the generation completes, typically 30-60s.

Servers: Inherited servers

Authentication: Global authentication

Request body

Required: true

Content type: application/json

GenerationRequest

Example: from_url

Image fetched from a URL

{
  "image_url": "https://customer-cdn.example.com/listings/42/hero.jpg",
  "background_id": "white-panels"
}

Example: from_base64

Inline base64

{
  "image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
  "background_id": "alpine-lot"
}

Example: custom_background

Workspace custom background (UUID from GET /v1/backgrounds)

{
  "image_url": "https://customer-cdn.example.com/listings/42/hero.jpg",
  "background_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Example: with_logo

Workspace logo in the top-left corner, 4:3 output

{
  "image_url": "https://customer-cdn.example.com/listings/42/hero.jpg",
  "background_id": "white-panels",
  "aspect_ratio": "4:3",
  "logo": {
    "id": "logo_1792240000000.png",
    "position": "top-left"
  }
}

Example: inline_logo

Inline logo at an exact position and size

{
  "image_url": "https://customer-cdn.example.com/listings/42/hero.jpg",
  "background_id": "white-panels",
  "logo": {
    "image_url": "https://customer-cdn.example.com/brand/dealer-17.png",
    "x": 0.05,
    "y": 0.05,
    "width": 0.25
  }
}

Example: multiple_logos

Dealer logo top-left and a brand badge bottom-right

{
  "image_url": "https://customer-cdn.example.com/listings/42/hero.jpg",
  "background_id": "white-panels",
  "logo": [
    {
      "id": "logo_1792240000000.png",
      "position": "top-left"
    },
    {
      "id": "logo_1792240000001.png",
      "position": "bottom-right",
      "width": 0.12
    }
  ]
}

Responses

200 Generation succeeded.

Headers:

Content type: application/json

Generation

Generated example:

{
  "id": "gen_01HXYZABCDEF...",
  "object": "generation",
  "status": "succeeded",
  "image_url": "https://example.com",
  "background_id": "white-panels",
  "credits_charged": 1,
  "created_at": "2026-11-22T00:40:56.262Z"
}
400, 401, 402, 405, 422, 500

Content type: application/json

Error

Generated example:

{
  "error": {
    "code": "invalid_api_key",
    "message": "",
    "request_id": ""
  }
}
429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

502 Temporary service error (`upstream_unavailable`, status 502 or 503). Retry with exponential backoff. A 503 means nothing was processed or charged and includes `Retry-After`.

Headers:

Content type: application/json

Error

Generated example

List your logos

Lists the workspace's logos, the same ones shown in the app's logo picker. Pass an id as logo.id to POST /v1/generations. With ?type=plate, lists the plate logos instead.

Servers: Inherited servers

Authentication: Global authentication

Query parameters

Responses

200 The workspace's logos, newest first.

Content type: application/json

LogoList

Generated example:

{
  "object": "list",
  "data": [
    {
      "id": "logo_1792240000000.png",
      "object": "logo",
      "type": "logo",
      "background": "#0f2a4a",
      "image_url": "https://example.com",
      "created_at": null
    }
  ]
}
401, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

Upload a logo

Stores a logo for the workspace (PNG, WebP or JPEG, up to 5 MB; use a PNG or WebP with a transparent background for the best result). A workspace holds up to seven logos; to use more, pass them inline to POST /v1/generations instead.

With ?type=plate, stores a plate logo: the design the generator puts on the license plate, filling the whole plate face. Upload it with its own background colour, or set background to fill a transparent one (white by default). Up to seven plate logos.

Servers: Inherited servers

Authentication: Global authentication

Query parameters

Request body

Required: true

Content type: application/json

LogoUpload

Set exactly one of image_url or image_base64.

Example:

{
  "image_url": "https://customer-cdn.example.com/brand/logo.png"
}

Responses

201 Logo stored.

Content type: application/json

Logo

Generated example:

{
  "id": "logo_1792240000000.png",
  "object": "logo",
  "type": "logo",
  "background": "#0f2a4a",
  "image_url": "https://example.com",
  "created_at": null
}
400, 401, 409, 422, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

Delete a logo

Servers: Inherited servers

Authentication: Global authentication

Path parameters

Query parameters

Responses

200 Logo deleted.

Content type: application/json

Generated example:

{
  "id": "",
  "object": "logo",
  "type": "logo",
  "deleted": true
}
401, 404, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

List available backgrounds

Lists the backgrounds you can pass as background_id to POST /v1/generations: the built-in catalogue followed by your workspace's custom backgrounds (created here or in the app). The set may change over time and is workspace-specific, so fetch it instead of hard-coding ids.

Servers: Inherited servers

Authentication: Global authentication

Responses

200 The list of available backgrounds.

Headers:

Content type: application/json

BackgroundList

Generated example:

{
  "object": "list",
  "data": [
    {
      "id": "white-panels",
      "name": "White Panels",
      "preview_url": null,
      "example_url": null,
      "custom": true,
      "feedback": ""
    }
  ]
}
401, 405, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

502 Temporary service error (`upstream_unavailable`, status 502 or 503). Retry with exponential backoff. A 503 means nothing was processed or charged and includes `Retry-After`.

Headers:

Content type: application/json

Error

Generated example

Create a custom background

Creates a background of your own, such as your showroom or a branded studio, from a text description, reference photos, or both. Renders a preview (a demo car on the new scene, exactly as generations will look) and returns it as example_url. Costs one credit; a rejected or failed request is not charged. The background is usable in POST /v1/generations straight away. Look at the preview and refine it with POST /v1/backgrounds/{id} until it is right.

Servers: Inherited servers

Authentication: Global authentication

Request body

Required: true

Content type: application/json

BackgroundCreate

Set description, reference_image_urls, or both.

Example:

{
  "description": "A bright showroom with light oak flooring and floor-to-ceiling windows"
}

Responses

201 Background created.

Content type: application/json

Background

Generated example:

{
  "id": "white-panels",
  "name": "White Panels",
  "preview_url": null,
  "example_url": null,
  "custom": true,
  "feedback": ""
}
400, 401, 402, 422, 500, 503

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

Refine a custom background

Changes a custom background and renders a new preview. description is the change to make ("make the floor darker and the lighting warmer"); everything else is kept. Costs one credit.

Servers: Inherited servers

Authentication: Global authentication

Path parameters

Request body

Required: true

Content type: application/json

BackgroundRefine

Set description, reference_image_urls, or both.

Example:

{
  "description": "Make the floor darker and the lighting warmer"
}

Responses

200 Background updated.

Content type: application/json

Background

Generated example

400, 401, 402, 404, 422, 500, 503

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

Delete a custom background

Photos already generated with it are not affected.

Servers: Inherited servers

Authentication: Global authentication

Path parameters

Responses

200 Background deleted.

Content type: application/json

Generated example:

{
  "id": "",
  "object": "background",
  "deleted": true
}
401, 404, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

Get your credit balance

Returns the workspace's current credit balance.

Servers: Inherited servers

Authentication: Global authentication

Responses

200 The workspace's current credit balance.

Headers:

Content type: application/json

Credits

Generated example:

{
  "object": "credits",
  "balance": 142
}
401, 405, 500

Content type: application/json

Error

Generated example

429 Per-key rate limit exceeded.

Headers:

Content type: application/json

Error

Generated example

502 Temporary service error (`upstream_unavailable`, status 502 or 503). Retry with exponential backoff. A 503 means nothing was processed or charged and includes `Retry-After`.

Headers:

Content type: application/json

Error

Generated example

Hide license plates

Finds every license plate in a car photo, including small plates on cars in the background, and hides it with a blur or a solid block. Everything else in the photo is unchanged: same size, same format (unless you ask for another), and location (GPS) metadata is removed by default. The image is returned inline and is not stored.

Included with any active subscription, at no credit cost, up to 2,000 photos per workspace per calendar month (UTC). Every request that passes validation counts towards the limit. Typically 2-4s.

Servers: Inherited servers

Authentication: Global authentication

Request body

Required: true

Content type: application/json

PlateRequest

Example: blur

Blur plates, keep the input format

{
  "image_url": "https://customer-cdn.example.com/listings/42/rear.jpg"
}

Example: block

White block, WebP output

{
  "image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
  "style": "block",
  "block_color": "#FFFFFF",
  "output_format": "webp"
}

Responses

200 Plates hidden.

Headers:

Content type: application/json

PlateBlur

Generated example:

{
  "id": "plt_9b75644c-ea48-45db-a966-6956cb214e7a",
  "object": "plate_blur",
  "status": "succeeded",
  "plates": [
    [
      621,
      344,
      693,
      680
    ]
  ],
  "image_base64": "",
  "mime_type": "image/jpeg",
  "created_at": "2026-11-22T00:40:56.298Z"
}
400, 401, 403, 405, 422, 429, 500, 503

Content type: application/json

Error

Generated example

Schemas

GenerationRequest

Type: object

Generated example:

{
  "image_url": "https://example.com",
  "image_base64": "",
  "background_id": "white-panels",
  "hide_license_plate": false,
  "license_plate_style": "plain",
  "license_plate_logo": {
    "id": "plate_1792240000000.bg-ffffff.png",
    "image_url": "https://example.com",
    "image_base64": "",
    "background": "#0F2A4A"
  },
  "center_car": false,
  "clean_car": false,
  "aspect_ratio": "1:1",
  "logo": {
    "id": "",
    "image_url": "https://example.com",
    "image_base64": "",
    "position": "bottom-right",
    "x": 0,
    "y": 0,
    "width": 0.05
  }
}

LogoPlacement

Type: object

Draws a logo onto the result. Set exactly one of id, image_url or image_base64. Place it with a position preset (default bottom-right) or with x and y. The result keeps a copy without the logo in your workspace library. A logo that can't be read returns 422 invalid_logo and no credit is charged.

Generated example:

{
  "id": "",
  "image_url": "https://example.com",
  "image_base64": "",
  "position": "bottom-right",
  "x": 0,
  "y": 0,
  "width": 0.05
}

LogoUpload

Type: object

Set exactly one of image_url or image_base64.

Generated example:

{
  "image_url": "https://example.com",
  "image_base64": "",
  "background": "#0F2A4A"
}

Logo

Type: object

Generated example:

{
  "id": "logo_1792240000000.png",
  "object": "logo",
  "type": "logo",
  "background": "#0f2a4a",
  "image_url": "https://example.com",
  "created_at": null
}

LogoList

Type: object

Generated example:

{
  "object": "list",
  "data": [
    {
      "id": "logo_1792240000000.png",
      "object": "logo",
      "type": "logo",
      "background": "#0f2a4a",
      "image_url": "https://example.com",
      "created_at": null
    }
  ]
}

BackgroundId

Type: string

Identifier of the background scene to apply: either a built-in scene slug (e.g. white-panels) or the UUID of one of your workspace's custom backgrounds. Call GET /v1/backgrounds for the current list of ids — the set changes over time and is workspace-specific, so do not hard-code it.

Example:

"white-panels"

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Generation

Type: object

Generated example:

{
  "id": "gen_01HXYZABCDEF...",
  "object": "generation",
  "status": "succeeded",
  "image_url": "https://example.com",
  "background_id": "white-panels",
  "credits_charged": 1,
  "created_at": "2026-11-22T00:40:56.319Z"
}

PlateRequest

Type: object

Generated example:

{
  "image_url": "https://example.com",
  "image_base64": "",
  "style": "blur",
  "block_color": "#FFFFFF",
  "output_format": "auto",
  "keep_metadata": false
}

PlateBlur

Type: object

Generated example:

{
  "id": "plt_9b75644c-ea48-45db-a966-6956cb214e7a",
  "object": "plate_blur",
  "status": "succeeded",
  "plates": [
    [
      621,
      344,
      693,
      680
    ]
  ],
  "image_base64": "",
  "mime_type": "image/jpeg",
  "created_at": "2026-11-22T00:40:56.324Z"
}

Background

Type: object

Generated example:

{
  "id": "white-panels",
  "name": "White Panels",
  "preview_url": null,
  "example_url": null,
  "custom": true,
  "feedback": ""
}

BackgroundCreate

Type: object

Set description, reference_image_urls, or both.

Generated example:

{
  "description": "",
  "reference_image_urls": [
    "https://example.com"
  ],
  "base_background_id": "white-panels",
  "name": ""
}

BackgroundRefine

Type: object

Set description, reference_image_urls, or both.

Generated example:

{
  "description": "",
  "reference_image_urls": [
    "https://example.com"
  ]
}

BackgroundList

Type: object

Generated example:

{
  "object": "list",
  "data": [
    {
      "id": "white-panels",
      "name": "White Panels",
      "preview_url": null,
      "example_url": null,
      "custom": true,
      "feedback": ""
    }
  ]
}

Credits

Type: object

Generated example:

{
  "object": "credits",
  "balance": 142
}

Error

Type: object

Generated example:

{
  "error": {
    "code": "invalid_api_key",
    "message": "",
    "request_id": ""
  }
}