# Car Background AI API

- **OpenAPI Version:** `3.2.0`
- **API Version:** `1.0.0`
- **Contact:**  <https://carbackground.ai> <hello@carbackground.ai>
- **License:** [Proprietary](https://carbackground.ai/terms)

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**

- [POST /v1/generations](#scalar-operation-post-v1generations)
- [GET /v1/logos](#scalar-operation-get-v1logos)
- [POST /v1/logos](#scalar-operation-post-v1logos)
- [DELETE /v1/logos/{id}](#scalar-operation-delete-v1logosid)
- [GET /v1/backgrounds](#scalar-operation-get-v1backgrounds)
- [POST /v1/backgrounds](#scalar-operation-post-v1backgrounds)
- [POST /v1/backgrounds/{id}](#scalar-operation-post-v1backgroundsid)
- [DELETE /v1/backgrounds/{id}](#scalar-operation-delete-v1backgroundsid)
- [GET /v1/credits](#scalar-operation-get-v1credits)
- [POST /v1/plates](#scalar-operation-post-v1plates)

**Schemas**

- [GenerationRequest](#scalar-schema-generationrequest)
- [LogoPlacement](#scalar-schema-logoplacement)
- [LogoUpload](#scalar-schema-logoupload)
- [Logo](#scalar-schema-logo)
- [LogoList](#scalar-schema-logolist)
- [BackgroundId](#scalar-schema-backgroundid)
- [Generation](#scalar-schema-generation)
- [PlateRequest](#scalar-schema-platerequest)
- [PlateBlur](#scalar-schema-plateblur)
- [Background](#scalar-schema-background)
- [BackgroundCreate](#scalar-schema-backgroundcreate)
- [BackgroundRefine](#scalar-schema-backgroundrefine)
- [BackgroundList](#scalar-schema-backgroundlist)
- [Credits](#scalar-schema-credits)
- [Error](#scalar-schema-error)

<a id="scalar-context-global-servers"></a>

## Servers

- **URL:** `https://api.carbackground.ai`
  - **Description:** Production

<a id="scalar-context-global-authentication"></a>

## Authentication

- **apiKey**: HTTP bearer (`cbg_*`)

  Pass your API key as `Authorization: Bearer cbg_<secret>`. Create and
  manage keys at <https://app.carbackground.ai/settings/api-keys>.

## Tags

### v1

## Operations

<a id="scalar-operation-post-v1generations"></a>

### Generate a background-replaced image

- **Method:** `POST`
- **Path:** `/v1/generations`
- **Operation ID:** `createGeneration`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Request body

**Required:** `true`

**Content type:** `application/json`

[GenerationRequest](#scalar-schema-generationrequest)

**Example: from_url**

Image fetched from a URL

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

**Example: from_base64**

Inline base64

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

**Example: custom_background**

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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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:**

- **`X-Request-Id`**

  Unique request identifier; include this when contacting support.

  `string`
- **`X-RateLimit-Limit`**

  Maximum tokens in the per-key bucket.

  `integer`
- **`X-RateLimit-Remaining`**

  Tokens remaining after this request.

  `integer`

**Content type:** `application/json`

[Generation](#scalar-schema-generation)

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "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

- `400` Request body is malformed (e.g., not valid JSON).
- `401` API key is missing, malformed, unknown, or revoked.
- `402` Workspace has no credits remaining.
- `405` HTTP method not supported on this endpoint.
- `422` Image input was missing, oversized, wrong type, or unfetchable.
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

<a id="scalar-example-2"></a>

**Generated example:**

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

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 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\`.&#x20;

**Headers:**

- **`Retry-After`**

  Seconds to wait before retrying (503 only).

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1logos"></a>

### List your logos

- **Method:** `GET`
- **Path:** `/v1/logos`
- **Operation ID:** `listLogos`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`type`**: `string`, possible values: `"logo", "plate"`, default: `"logo"`

  Which logo library: `logo` (drawn on finished photos) or `plate`
  (put on the car's license plate by the generator).

#### Responses

##### 200 The workspace's logos, newest first.

**Content type:** `application/json`

[LogoList](#scalar-schema-logolist)

<a id="scalar-example-3"></a>

**Generated example:**

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

##### 401, 500

- `401` API key is missing, malformed, unknown, or revoked.
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1logos"></a>

### Upload a logo

- **Method:** `POST`
- **Path:** `/v1/logos`
- **Operation ID:** `createLogo`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`type`**: `string`, possible values: `"logo", "plate"`, default: `"logo"`

  Which logo library: `logo` (drawn on finished photos) or `plate`
  (put on the car's license plate by the generator).

#### Request body

**Required:** `true`

**Content type:** `application/json`

[LogoUpload](#scalar-schema-logoupload)

Set exactly one of `image_url` or `image_base64`.

**Example:**

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

#### Responses

##### 201 Logo stored.

**Content type:** `application/json`

[Logo](#scalar-schema-logo)

<a id="scalar-example-4"></a>

**Generated example:**

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

##### 400, 401, 409, 422, 500

- `400` Request body is malformed (e.g., not valid JSON).
- `401` API key is missing, malformed, unknown, or revoked.
- `409` The workspace already has seven logos of this type (\`logo_limit_reached\`).
- `422` Image input was missing, oversized, wrong type, or unfetchable.
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1logosid"></a>

### Delete a logo

- **Method:** `DELETE`
- **Path:** `/v1/logos/{id}`
- **Operation ID:** `deleteLogo`
- **Tags:** v1

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`id` (required)**: `string`

  **Example:**

  ```json
  "logo_1792240000000.png"
  ```

#### Query parameters

- **`type`**: `string`, possible values: `"logo", "plate"`, default: `"logo"`

  Which logo library: `logo` (drawn on finished photos) or `plate`
  (put on the car's license plate by the generator).

#### Responses

##### 200 Logo deleted.

**Content type:** `application/json`

- **`deleted` (required)**: `boolean`, possible values: `true`
- **`id` (required)**: `string`
- **`object` (required)**: `string`, possible values: `"logo"`
- **`type` (required)**: `string`, possible values: `"logo", "plate"`

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "logo",
  "type": "logo",
  "deleted": true
}
```

##### 401, 404, 500

- `401` API key is missing, malformed, unknown, or revoked.
- `404` No logo with that id in the workspace (\`not_found\`).
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1backgrounds"></a>

### List available backgrounds

- **Method:** `GET`
- **Path:** `/v1/backgrounds`
- **Operation ID:** `listBackgrounds`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Responses

##### 200 The list of available backgrounds.

**Headers:**

- **`X-Request-Id`**

  `string`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`

**Content type:** `application/json`

[BackgroundList](#scalar-schema-backgroundlist)

<a id="scalar-example-6"></a>

**Generated example:**

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

##### 401, 405, 500

- `401` API key is missing, malformed, unknown, or revoked.
- `405` HTTP method not supported on this endpoint.
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 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\`.&#x20;

**Headers:**

- **`Retry-After`**

  Seconds to wait before retrying (503 only).

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1backgrounds"></a>

### Create a custom background

- **Method:** `POST`
- **Path:** `/v1/backgrounds`
- **Operation ID:** `createBackground`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Request body

**Required:** `true`

**Content type:** `application/json`

[BackgroundCreate](#scalar-schema-backgroundcreate)

Set `description`, `reference_image_urls`, or both.

**Example:**

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

#### Responses

##### 201 Background created.

**Content type:** `application/json`

[Background](#scalar-schema-background)

<a id="scalar-example-7"></a>

**Generated example:**

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

##### 400, 401, 402, 422, 500, 503

- `400` Request body is malformed (e.g., not valid JSON).
- `401` API key is missing, malformed, unknown, or revoked.
- `402` The workspace has no credits left (\`insufficient_credits\`).
- `422` The description can't be turned into a background (\`background_rejected\`; the message says why), a reference image is invalid (\`invalid_image\`), or the preview could not be rendered (\`generation_failed\`). Nothing is charged.&#x20;
- `500` Unexpected server error. Include \`request_id\` when contacting support.
- `503` The preview could not be rendered (\`generation_failed\`). Nothing is charged; retry.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1backgroundsid"></a>

### Refine a custom background

- **Method:** `POST`
- **Path:** `/v1/backgrounds/{id}`
- **Operation ID:** `refineBackground`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`id` (required)**: `string`, format: `uuid`

  The id of one of your custom backgrounds.

#### Request body

**Required:** `true`

**Content type:** `application/json`

[BackgroundRefine](#scalar-schema-backgroundrefine)

Set `description`, `reference_image_urls`, or both.

**Example:**

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

#### Responses

##### 200 Background updated.

**Content type:** `application/json`

[Background](#scalar-schema-background)

[Generated example](#scalar-example-7)

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

- `400` Request body is malformed (e.g., not valid JSON).
- `401` API key is missing, malformed, unknown, or revoked.
- `402` The workspace has no credits left (\`insufficient_credits\`).
- `404` No custom background with that id in the workspace (\`not_found\`).
- `422` The description can't be turned into a background (\`background_rejected\`; the message says why), a reference image is invalid (\`invalid_image\`), or the preview could not be rendered (\`generation_failed\`). Nothing is charged.&#x20;
- `500` Unexpected server error. Include \`request_id\` when contacting support.
- `503` The preview could not be rendered (\`generation_failed\`). Nothing is charged; retry.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-delete-v1backgroundsid"></a>

### Delete a custom background

- **Method:** `DELETE`
- **Path:** `/v1/backgrounds/{id}`
- **Operation ID:** `deleteBackground`
- **Tags:** v1

Photos already generated with it are not affected.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`id` (required)**: `string`, format: `uuid`

  The id of one of your custom backgrounds.

#### Responses

##### 200 Background deleted.

**Content type:** `application/json`

- **`deleted` (required)**: `boolean`, possible values: `true`
- **`id` (required)**: `string`
- **`object` (required)**: `string`, possible values: `"background"`

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "background",
  "deleted": true
}
```

##### 401, 404, 500

- `401` API key is missing, malformed, unknown, or revoked.
- `404` No custom background with that id in the workspace (\`not_found\`).
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-get-v1credits"></a>

### Get your credit balance

- **Method:** `GET`
- **Path:** `/v1/credits`
- **Operation ID:** `getCredits`
- **Tags:** v1

Returns the workspace's current credit balance.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Responses

##### 200 The workspace's current credit balance.

**Headers:**

- **`X-Request-Id`**

  `string`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`

**Content type:** `application/json`

[Credits](#scalar-schema-credits)

<a id="scalar-example-9"></a>

**Generated example:**

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

##### 401, 405, 500

- `401` API key is missing, malformed, unknown, or revoked.
- `405` HTTP method not supported on this endpoint.
- `500` Unexpected server error. Include \`request_id\` when contacting support.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 429 Per-key rate limit exceeded.

**Headers:**

- **`Retry-After`**

  Seconds until at least one token refills.

  `integer`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`
- **`X-RateLimit-Reset`**

  Unix epoch seconds when the bucket has capacity again.

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

##### 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\`.&#x20;

**Headers:**

- **`Retry-After`**

  Seconds to wait before retrying (503 only).

  `integer`

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

<a id="scalar-operation-post-v1plates"></a>

### Hide license plates

- **Method:** `POST`
- **Path:** `/v1/plates`
- **Operation ID:** `hidePlates`
- **Tags:** v1

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](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Request body

**Required:** `true`

**Content type:** `application/json`

[PlateRequest](#scalar-schema-platerequest)

**Example: blur**

Blur plates, keep the input format

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

**Example: block**

White block, WebP output

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

#### Responses

##### 200 Plates hidden.

**Headers:**

- **`X-Request-Id`**

  `string`
- **`X-RateLimit-Limit`**

  `integer`
- **`X-RateLimit-Remaining`**

  `integer`

**Content type:** `application/json`

[PlateBlur](#scalar-schema-plateblur)

<a id="scalar-example-10"></a>

**Generated example:**

```json
{
  "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

- `400` Request body is malformed (e.g., not valid JSON).
- `401` API key is missing, malformed, unknown, or revoked.
- `403` The endpoint requires an active subscription on the workspace.
- `405` HTTP method not supported on this endpoint.
- `422` Image input was missing, oversized, wrong type, or unfetchable.
- `429` Per-key rate limit exceeded (\`rate_limited\`, with \`Retry-After\`), or the workspace's monthly plate limit is reached (\`plate_quota_exceeded\`; contact us for a higher limit).&#x20;
- `500` Unexpected server error. Include \`request_id\` when contacting support.
- `503` Plate detection failed (\`detection_failed\`). Retry the request.

**Content type:** `application/json`

[Error](#scalar-schema-error)

[Generated example](#scalar-example-2)

## Schemas

<a id="scalar-schema-generationrequest"></a>

### GenerationRequest

**Type:** `object`

- **`background_id` (required)**: `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.
- **`aspect_ratio`**: `string`, possible values: `"1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9"`

  Output aspect ratio; omit to keep the input photo's. The scene is
  extended or the view tightened to fit, never by adding parts of
  the car that are not in the photo. Interior and detail photos keep
  their original ratio.
- **`center_car`**: `boolean`, default: `false`

  **Experimental.** Frame the car like a dealership listing photo:
  centred, enlarged and levelled if the photo was taken crooked,
  keeping its viewing angle. A car cut off at an edge of the photo
  stays cut off at that edge. `false` keeps the car's original size
  and position. Applies to exterior photos only. Results can be
  unexpected: details of the car may be invented or not fully kept.
- **`clean_car`**: `boolean`, default: `false`

  **Experimental.** Show the car freshly washed: removes dirt a car
  wash would remove (dust, mud, water spots, insects) and keeps
  permanent marks such as scratches, dents and rust. `false` keeps
  the car as photographed. Applies to exterior photos only. Results
  can be unexpected: details of the car may be invented or not fully
  kept.
- **`hide_license_plate`**: `boolean`, default: `false`

  Hide a legible license plate, in the style set by
  `license_plate_style`. Photos without a visible plate are left
  unchanged. Applies to exterior photos only.
- **`image_base64`**: `string`

  Base64-encoded image bytes. Accepts both raw base64 and a
  `data:image/...;base64,...` data URL. Same size and type
  constraints as `image_url`.
- **`image_url`**: `string`, format: `uri`

  HTTPS URL of the source car photo. Maximum 50 MB. Supported
  content-types: image/jpeg, image/png, image/webp. Either
  `image_url` or `image_base64` must be set, not both.
- **`license_plate_logo`**: `object`

  Required with `license_plate_style: logo`. Set exactly one of
  `id` (a plate logo from `GET /v1/logos?type=plate`),
  `image_url` or `image_base64`. The logo fills the whole plate
  face; a transparent logo sits on its plate colour.
  - **`background`**: `string`, pattern: `^#[0-9a-fA-F]{6}$`

    Inline logos only: the plate colour behind a transparent logo.
    Default white. A stored plate logo uses its own.
  - **`id`**: `string`
  - **`image_base64`**: `string`
  - **`image_url`**: `string`, format: `uri`
- **`license_plate_style`**: `string`, possible values: `"plain", "blur", "logo"`, default: `"plain"`

  How `hide_license_plate` hides the plate. `plain` replaces it with
  a plain plate of the same colour (no characters, symbols or country
  band); `blur` blurs the whole plate so nothing on it can be read,
  keeping its shape and position; `logo` replaces it with a plate
  showing `license_plate_logo`, following the plate's angle. Ignored
  unless `hide_license_plate` is true. With `logo`, a car far from
  the camera may come out a little larger.
- **`logo`**

  One logo, or a list of up to seven drawn in order (later ones on
  top).

  **One of:**
  - [LogoPlacement](#scalar-schema-logoplacement)

    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.
  - array of [LogoPlacement](#scalar-schema-logoplacement), minItems: `1`, maxItems: `7`

<a id="scalar-example-11"></a>

**Generated example:**

```json
{
  "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
  }
}
```

<a id="scalar-schema-logoplacement"></a>

### 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.

- **`id`**: `string`

  A logo from `GET /v1/logos`.
- **`image_base64`**: `string`

  The same, base64-encoded (raw or a data URL).
- **`image_url`**: `string`, format: `uri`

  A PNG, WebP or JPEG logo (up to 5 MB), not stored.
- **`position`**: `string`, possible values: `"top-left", "top-right", "bottom-left", "bottom-right", "top-center"`, default: `"bottom-right"`

  Corner presets sit 4% (of the shorter side) in from the edges;
  `top-center` suits a wide logo shown like wall signage.
- **`width`**: `number`, minimum: `0.05`, maximum: `1`

  Logo width as a fraction of the image width. Default 0.2 (0.3 for
  `top-center`). The height follows the logo's own proportions.
- **`x`**: `number`, minimum: `0`, maximum: `1`

  Instead of `position`: the logo's left edge as a fraction of the
  image width. Set together with `y`. Kept inside the image.
- **`y`**: `number`, minimum: `0`, maximum: `1`

  The logo's top edge as a fraction of the image height.

<a id="scalar-example-12"></a>

**Generated example:**

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

<a id="scalar-schema-logoupload"></a>

### LogoUpload

**Type:** `object`

Set exactly one of `image_url` or `image_base64`.

- **`background`**: `string`, pattern: `^#[0-9a-fA-F]{6}$`

  Plate logos only (`?type=plate`): the colour that fills the logo's
  transparent pixels, as the plate's background. Default white.
- **`image_base64`**: `string`
- **`image_url`**: `string`, format: `uri`

<a id="scalar-example-13"></a>

**Generated example:**

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

<a id="scalar-schema-logo"></a>

### Logo

**Type:** `object`

- **`created_at` (required)**: `string | null`, format: `date-time`
- **`id` (required)**: `string`
- **`image_url` (required)**: `string`, format: `uri`

  Signed URL of the logo, valid for 7 days.
- **`object` (required)**: `string`, possible values: `"logo"`
- **`type` (required)**: `string`, possible values: `"logo", "plate"`

  `logo` for logos drawn on photos, `plate` for plate logos.
- **`background`**: `string`

  Plate logos only: the plate colour shown behind a transparent
  logo, as set on upload.

<a id="scalar-example-14"></a>

**Generated example:**

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

<a id="scalar-schema-logolist"></a>

### LogoList

**Type:** `object`

- **`data` (required)**: array of [Logo](#scalar-schema-logo)
- **`object` (required)**: `string`, possible values: `"list"`

<a id="scalar-example-15"></a>

**Generated example:**

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

<a id="scalar-schema-backgroundid"></a>

### 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:**

```json
"white-panels"
```

**Example:**

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

<a id="scalar-schema-generation"></a>

### Generation

**Type:** `object`

- **`background_id` (required)**: `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.
- **`created_at` (required)**: `string`, format: `date-time`
- **`credits_charged` (required)**: `integer`
- **`id` (required)**: `string`

  Unique generation identifier.
- **`image_url` (required)**: `string`, format: `uri`

  Signed URL to the generated image, with the logo drawn on when
  `logo` was set. Valid for 7 days.
- **`object` (required)**: `string`, possible values: `"generation"`
- **`status` (required)**: `string`, possible values: `"succeeded"`

<a id="scalar-example-16"></a>

**Generated example:**

```json
{
  "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"
}
```

<a id="scalar-schema-platerequest"></a>

### PlateRequest

**Type:** `object`

- **`block_color`**: `string`, default: `"#000000"`

  Hex colour of the block when `style` is `block`.
- **`image_base64`**: `string`

  Base64-encoded image bytes, raw or as a `data:image/...;base64,...`
  data URL. Same size and type constraints as `image_url`.
- **`image_url`**: `string`, format: `uri`

  HTTPS URL of the car photo. Maximum 20 MB. Supported content-types:
  image/jpeg, image/png, image/webp. Either `image_url` or
  `image_base64` must be set, not both.
- **`keep_metadata`**: `boolean`, default: `false`

  Keep the photo's EXIF metadata. By default it is removed, including
  the GPS location where the photo was taken.
- **`output_format`**: `string`, possible values: `"auto", "jpeg", "png", "webp"`, default: `"auto"`

  `auto` returns the same format as the input.
- **`style`**: `string`, possible values: `"blur", "block"`, default: `"blur"`

  Blur the plate, or cover it with a solid block.

<a id="scalar-example-17"></a>

**Generated example:**

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

<a id="scalar-schema-plateblur"></a>

### PlateBlur

**Type:** `object`

- **`created_at` (required)**: `string`, format: `date-time`
- **`id` (required)**: `string`
- **`image_base64` (required)**: `string`

  The result image, base64-encoded.
- **`mime_type` (required)**: `string`, possible values: `"image/jpeg", "image/png", "image/webp"`
- **`object` (required)**: `string`, possible values: `"plate_blur"`
- **`plates` (required)**: `array`

  The areas that were hidden (each plate plus a small margin), as
  `[ymin, xmin, ymax, xmax]` normalised to 0-1000 of the image height
  and width. Empty when no plate was found (the image is still
  returned, with metadata removed unless `keep_metadata` is set).

  **Items:**

  `array of integer`, minItems: `4`, maxItems: `4`
- **`status` (required)**: `string`, possible values: `"succeeded"`

<a id="scalar-example-18"></a>

**Generated example:**

```json
{
  "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"
}
```

<a id="scalar-schema-background"></a>

### Background

**Type:** `object`

- **`custom` (required)**: `boolean`

  `true` for a custom background owned by your workspace, `false`
  for a built-in scene.
- **`example_url` (required)**: `string | null`, format: `uri`

  Example showing a sample car composited on the scene. For custom
  backgrounds a signed URL valid for 7 days, or `null` if it has no
  preview yet.
- **`id` (required)**: `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.
- **`name` (required)**: `string`

  Human-readable display name.
- **`preview_url` (required)**: `string | null`, format: `uri`

  Clean, car-free preview of the background scene. `null` for custom
  backgrounds.
- **`feedback`**: `string`

  Only when creating or refining: the part of the request that
  could not be honoured, if any.

<a id="scalar-example-19"></a>

**Generated example:**

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

<a id="scalar-schema-backgroundcreate"></a>

### BackgroundCreate

**Type:** `object`

Set `description`, `reference_image_urls`, or both.

- **`base_background_id`**: `string`

  A built-in background to start from; `description` then says what
  to change.
- **`description`**: `string`, maxLength: `2000`

  The scene, e.g. walls, floor, lighting and setting.
- **`name`**: `string`, maxLength: `80`

  Display name. One is suggested if omitted.
- **`reference_image_urls`**: `array`, maxItems: `3`

  Photos of the place or style to recreate (JPEG, PNG or WebP, up to 20 MB each).

  **Items:**

  `string`, format: `uri`

<a id="scalar-example-20"></a>

**Generated example:**

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

<a id="scalar-schema-backgroundrefine"></a>

### BackgroundRefine

**Type:** `object`

Set `description`, `reference_image_urls`, or both.

- **`description`**: `string`, maxLength: `2000`

  The change to make to the background.
- **`reference_image_urls`**: `array`, maxItems: `3`

  **Items:**

  `string`, format: `uri`

<a id="scalar-example-21"></a>

**Generated example:**

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

<a id="scalar-schema-backgroundlist"></a>

### BackgroundList

**Type:** `object`

- **`data` (required)**: array of [Background](#scalar-schema-background)
- **`object` (required)**: `string`, possible values: `"list"`

<a id="scalar-example-22"></a>

**Generated example:**

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

<a id="scalar-schema-credits"></a>

### Credits

**Type:** `object`

- **`balance` (required)**: `integer`

  Credits currently available to the workspace.
- **`object` (required)**: `string`, possible values: `"credits"`

<a id="scalar-example-23"></a>

**Generated example:**

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

<a id="scalar-schema-error"></a>

### Error

**Type:** `object`

- **`error` (required)**: `object`
  - **`code` (required)**: `string`, possible values: `"invalid_api_key", "insufficient_credits", "invalid_image", "invalid_request", "rate_limited", "method_not_allowed", "generation_failed", "subscription_required", "plate_quota_exceeded", "detection_failed", "invalid_logo", "logo_limit_reached", "internal_error", "upstream_unavailable", "not_found"`
  - **`message` (required)**: `string`

    Human-readable summary, may change between releases.
  - **`request_id` (required)**: `string`

    Echoes `X-Request-Id` so it appears in customer logs.

<a id="scalar-example-24"></a>

**Generated example:**

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