3.2.01.0.0The 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.
Operations
Schemas
https://api.carbackground.aiapiKey: HTTP bearer (cbg_*)
Pass your API key as Authorization: Bearer cbg_<secret>. Create and
manage keys at https://app.carbackground.ai/settings/api-keys.
POST/v1/generationscreateGenerationSubmit 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
Required: true
Content type: application/json
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
}
]
}
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
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 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
Generated example:
{
"error": {
"code": "invalid_api_key",
"message": "",
"request_id": ""
}
}
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
Headers:
Retry-After
Seconds to wait before retrying (503 only).
integer
Content type: application/json
GET/v1/logoslistLogosLists 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
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).
Content type: application/json
Generated example:
{
"object": "list",
"data": [
{
"id": "logo_1792240000000.png",
"object": "logo",
"type": "logo",
"background": "#0f2a4a",
"image_url": "https://example.com",
"created_at": null
}
]
}
401 API key is missing, malformed, unknown, or revoked.500 Unexpected server error. Include `request_id` when contacting support.Content type: application/json
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
POST/v1/logoscreateLogoStores 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
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).
Required: true
Content type: application/json
Set exactly one of image_url or image_base64.
Example:
{
"image_url": "https://customer-cdn.example.com/brand/logo.png"
}
Content type: application/json
Generated example:
{
"id": "logo_1792240000000.png",
"object": "logo",
"type": "logo",
"background": "#0f2a4a",
"image_url": "https://example.com",
"created_at": null
}
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
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
DELETE/v1/logos/{id}deleteLogoServers: Inherited servers
Authentication: Global authentication
id (required): string
Example:
"logo_1792240000000.png"
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).
Content type: application/json
deleted (required): boolean, possible values: trueid (required): stringobject (required): string, possible values: "logo"type (required): string, possible values: "logo", "plate"Generated example:
{
"id": "",
"object": "logo",
"type": "logo",
"deleted": true
}
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
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
GET/v1/backgroundslistBackgroundsLists 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
Headers:
X-Request-Id
string
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
Content type: application/json
Generated example:
{
"object": "list",
"data": [
{
"id": "white-panels",
"name": "White Panels",
"preview_url": null,
"example_url": null,
"custom": true,
"feedback": ""
}
]
}
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
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
Headers:
Retry-After
Seconds to wait before retrying (503 only).
integer
Content type: application/json
POST/v1/backgroundscreateBackgroundCreates 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
Required: true
Content type: application/json
Set description, reference_image_urls, or both.
Example:
{
"description": "A bright showroom with light oak flooring and floor-to-ceiling windows"
}
Content type: application/json
Generated example:
{
"id": "white-panels",
"name": "White Panels",
"preview_url": null,
"example_url": null,
"custom": true,
"feedback": ""
}
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. 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
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
POST/v1/backgrounds/{id}refineBackgroundChanges 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
id (required): string, format: uuid
The id of one of your custom backgrounds.
Required: true
Content type: application/json
Set description, reference_image_urls, or both.
Example:
{
"description": "Make the floor darker and the lighting warmer"
}
Content type: application/json
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. 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
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
DELETE/v1/backgrounds/{id}deleteBackgroundPhotos already generated with it are not affected.
Servers: Inherited servers
Authentication: Global authentication
id (required): string, format: uuid
The id of one of your custom backgrounds.
Content type: application/json
deleted (required): boolean, possible values: trueid (required): stringobject (required): string, possible values: "background"Generated example:
{
"id": "",
"object": "background",
"deleted": true
}
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
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
GET/v1/creditsgetCreditsReturns the workspace's current credit balance.
Servers: Inherited servers
Authentication: Global authentication
Headers:
X-Request-Id
string
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
Content type: application/json
Generated example:
{
"object": "credits",
"balance": 142
}
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
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
Headers:
Retry-After
Seconds to wait before retrying (503 only).
integer
Content type: application/json
POST/v1/plateshidePlatesFinds 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
Required: true
Content type: application/json
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"
}
Headers:
X-Request-Id
string
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
Content type: application/json
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 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). 500 Unexpected server error. Include `request_id` when contacting support.503 Plate detection failed (`detection_failed`). Retry the request.Content type: application/json
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:
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, minItems: 1, maxItems: 7
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
}
}
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.
Generated example:
{
"id": "",
"image_url": "https://example.com",
"image_base64": "",
"position": "bottom-right",
"x": 0,
"y": 0,
"width": 0.05
}
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
Generated example:
{
"image_url": "https://example.com",
"image_base64": "",
"background": "#0F2A4A"
}
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.
Generated example:
{
"id": "logo_1792240000000.png",
"object": "logo",
"type": "logo",
"background": "#0f2a4a",
"image_url": "https://example.com",
"created_at": null
}
Type: object
data (required): array of Logoobject (required): string, possible values: "list"Generated example:
{
"object": "list",
"data": [
{
"id": "logo_1792240000000.png",
"object": "logo",
"type": "logo",
"background": "#0f2a4a",
"image_url": "https://example.com",
"created_at": null
}
]
}
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"
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"
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"
}
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.
Generated example:
{
"image_url": "https://example.com",
"image_base64": "",
"style": "blur",
"block_color": "#FFFFFF",
"output_format": "auto",
"keep_metadata": false
}
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"
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"
}
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.
Generated example:
{
"id": "white-panels",
"name": "White Panels",
"preview_url": null,
"example_url": null,
"custom": true,
"feedback": ""
}
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
Generated example:
{
"description": "",
"reference_image_urls": [
"https://example.com"
],
"base_background_id": "white-panels",
"name": ""
}
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
Generated example:
{
"description": "",
"reference_image_urls": [
"https://example.com"
]
}
Type: object
data (required): array of Backgroundobject (required): string, possible values: "list"Generated example:
{
"object": "list",
"data": [
{
"id": "white-panels",
"name": "White Panels",
"preview_url": null,
"example_url": null,
"custom": true,
"feedback": ""
}
]
}
Type: object
balance (required): integer
Credits currently available to the workspace.
object (required): string, possible values: "credits"
Generated example:
{
"object": "credits",
"balance": 142
}
Type: object
error (required): objectcode (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.
Generated example:
{
"error": {
"code": "invalid_api_key",
"message": "",
"request_id": ""
}
}