{
  "openapi": "3.1.0",
  "info": {
    "title": "BackgroundErase API",
    "summary": "Background removal and replacement API",
    "description": "Remove image backgrounds, return transparent cutouts or alpha masks, and optionally replace backgrounds with solid colors or background images.",
    "version": "2.0.0",
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-BackgroundErase-Proprietary"
    },
    "contact": {
      "name": "BackgroundErase",
      "url": "https://backgrounderase.com/docs"
    }
  },
  "servers": [
    {
      "url": "https://api.backgrounderase.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Images",
      "description": "Background removal and image compositing"
    },
    {
      "name": "Account",
      "description": "API key validation and account metadata"
    },
    {
      "name": "Health",
      "description": "Service health checks"
    }
  ],
  "paths": {
    "/v2": {
      "post": {
        "tags": [
          "Images"
        ],
        "operationId": "processImage",
        "summary": "Remove an image background",
        "description": "Accepts multipart uploads, JSON base64 or URL input, or legacy raw image bytes. By default the response is binary image data. When the request body is JSON, the response is JSON containing a base64-encoded image or mask. Exactly one primary image source should be supplied.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Input image and processing options. Maximum input size is 30 MB by default and decoded images may not exceed 100 megapixels by default.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ProcessImageMultipartRequest"
              },
              "encoding": {
                "image_file": {
                  "contentType": "image/png, image/jpeg, image/webp, image/bmp, image/tiff, image/gif, image/heic, image/heif"
                },
                "bg_image_file": {
                  "contentType": "image/png, image/jpeg, image/webp, image/bmp, image/tiff, image/gif, image/heic, image/heif"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProcessImageJsonRequest"
              },
              "examples": {
                "image_base64": {
                  "summary": "Base64 image input",
                  "value": {
                    "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
                    "format": "png",
                    "channels": "rgba",
                    "size": "full"
                  }
                },
                "image_url": {
                  "summary": "URL image input",
                  "value": {
                    "image_url": "https://example.com/photo.jpg",
                    "format": "jpg",
                    "bg_color": "#ffffff"
                  }
                },
                "alpha_mask": {
                  "summary": "Alpha mask output",
                  "value": {
                    "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
                    "channels": "alpha",
                    "crop": true
                  }
                }
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/bmp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/tiff": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/heic": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/heif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed image or mask. Binary requests return binary image bytes. JSON requests return base64-encoded JSON.",
            "headers": {
              "X-Request-ID": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/bmp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/tiff": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/gif": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ProcessedImageJsonResponse"
                    },
                    {
                      "$ref": "#/components/schemas/AlphaMaskJsonResponse"
                    }
                  ]
                },
                "examples": {
                  "image": {
                    "summary": "Processed image response",
                    "value": {
                      "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
                      "mime": "image/jpeg",
                      "width": 1200,
                      "height": 800
                    }
                  },
                  "mask": {
                    "summary": "Alpha mask response",
                    "value": {
                      "mask": "iVBORw0KGgoAAAANSUhEUgAA...",
                      "mime": "image/png",
                      "width": 1200,
                      "height": 800
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "502": {
            "$ref": "#/components/responses/ProcessingFailed"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v2/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getAccount",
        "summary": "Validate an API key",
        "description": "Returns safe account metadata for the provided API key.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The API key is valid.",
            "headers": {
              "X-Request-ID": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountResponse"
                },
                "example": {
                  "status": "ok",
                  "api_key": {
                    "valid": true,
                    "mode": "live",
                    "fingerprint": "tok_fp_a1b2c3d4e5f6"
                  },
                  "account": {
                    "email": "user@example.com",
                    "plan": "Business",
                    "subscription_status": "active",
                    "billing_model": "metered_monthly",
                    "usage_unit": "image"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          }
        }
      }
    },
    "/v2/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getVersionedHealth",
        "summary": "Check service health",
        "security": [],
        "responses": {
          "200": {
            "$ref": "#/components/responses/HealthOk"
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getHealth",
        "summary": "Check service health",
        "security": [],
        "responses": {
          "200": {
            "$ref": "#/components/responses/HealthOk"
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getRoot",
        "summary": "Check service health",
        "security": [],
        "responses": {
          "200": {
            "$ref": "#/components/responses/HealthOk"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Send your BackgroundErase API key in this header."
      }
    },
    "headers": {
      "RequestId": {
        "description": "Unique request identifier for tracing and support.",
        "schema": {
          "type": "string",
          "example": "0d4f5484ef544c58935c79064d3980b8"
        }
      }
    },
    "schemas": {
      "ProcessImageMultipartRequest": {
        "type": "object",
        "description": "Multipart image upload. Provide exactly one primary image source: image_file, image_base64, image_file_b64, or image_url. Provide at most one background image source.",
        "properties": {
          "image_file": {
            "type": "string",
            "format": "binary",
            "description": "Primary image file upload."
          },
          "image_base64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Primary image as base64. Data URLs are accepted."
          },
          "image_file_b64": {
            "type": "string",
            "contentEncoding": "base64",
            "deprecated": true,
            "description": "Legacy alias for image_base64."
          },
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "HTTP or HTTPS URL for the primary image."
          },
          "imageUrl": {
            "type": "string",
            "format": "uri",
            "deprecated": true,
            "description": "Legacy camelCase alias for image_url."
          },
          "bg_image_file": {
            "type": "string",
            "format": "binary",
            "description": "Optional background image file. Cannot be used with channels=alpha."
          },
          "bg_image_base64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Optional background image as base64. Cannot be used with channels=alpha."
          },
          "bg_image_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional HTTP or HTTPS URL for a background image. Cannot be used with channels=alpha."
          },
          "format": {
            "$ref": "#/components/schemas/OutputFormat"
          },
          "channels": {
            "$ref": "#/components/schemas/Channels"
          },
          "size": {
            "$ref": "#/components/schemas/Size"
          },
          "crop": {
            "type": "boolean",
            "default": false,
            "description": "Crop transparent padding from the output. Form values such as true, 1, yes, and y are accepted."
          },
          "despill": {
            "type": "boolean",
            "default": false,
            "description": "Apply green-screen despill cleanup. Form values such as true, 1, yes, and y are accepted."
          },
          "bg_color": {
            "$ref": "#/components/schemas/BackgroundColor"
          },
          "bg_fit": {
            "$ref": "#/components/schemas/BackgroundFit"
          },
          "bg_position": {
            "$ref": "#/components/schemas/BackgroundPosition"
          }
        },
        "anyOf": [
          {
            "required": [
              "image_file"
            ]
          },
          {
            "required": [
              "image_base64"
            ]
          },
          {
            "required": [
              "image_file_b64"
            ]
          },
          {
            "required": [
              "image_url"
            ]
          },
          {
            "required": [
              "imageUrl"
            ]
          }
        ]
      },
      "ProcessImageJsonRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ImageBase64JsonRequest"
          },
          {
            "$ref": "#/components/schemas/ImageUrlJsonRequest"
          },
          {
            "$ref": "#/components/schemas/LegacyImageJsonRequest"
          }
        ]
      },
      "ImageBase64JsonRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ProcessingOptions"
          },
          {
            "type": "object",
            "required": [
              "image_base64"
            ],
            "properties": {
              "image_base64": {
                "type": "string",
                "contentEncoding": "base64",
                "description": "Primary image as base64. Data URLs are accepted."
              },
              "bg_image_base64": {
                "type": "string",
                "contentEncoding": "base64",
                "description": "Optional background image as base64. Cannot be used with channels=alpha."
              },
              "bg_image_url": {
                "type": "string",
                "format": "uri",
                "description": "Optional HTTP or HTTPS URL for a background image. Cannot be used with channels=alpha."
              }
            }
          }
        ]
      },
      "ImageUrlJsonRequest": {
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProcessingOptions"
              },
              {
                "type": "object",
                "required": [
                  "image_url"
                ],
                "properties": {
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "HTTP or HTTPS URL for the primary image."
                  },
                  "bg_image_base64": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "Optional background image as base64. Cannot be used with channels=alpha."
                  },
                  "bg_image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional HTTP or HTTPS URL for a background image. Cannot be used with channels=alpha."
                  }
                }
              }
            ]
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProcessingOptions"
              },
              {
                "type": "object",
                "required": [
                  "imageUrl"
                ],
                "properties": {
                  "imageUrl": {
                    "type": "string",
                    "format": "uri",
                    "deprecated": true,
                    "description": "Legacy camelCase alias for image_url."
                  },
                  "bg_image_base64": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "Optional background image as base64. Cannot be used with channels=alpha."
                  },
                  "bg_image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional HTTP or HTTPS URL for a background image. Cannot be used with channels=alpha."
                  }
                }
              }
            ]
          }
        ]
      },
      "LegacyImageJsonRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ProcessingOptions"
          },
          {
            "type": "object",
            "required": [
              "image"
            ],
            "properties": {
              "image": {
                "type": "string",
                "contentEncoding": "base64",
                "deprecated": true,
                "description": "Legacy primary image field. This mode always returns an alpha mask JSON response."
              }
            }
          }
        ],
        "description": "Legacy JSON request shape. The service forces channels=alpha when image is used."
      },
      "ProcessingOptions": {
        "type": "object",
        "properties": {
          "format": {
            "$ref": "#/components/schemas/OutputFormat"
          },
          "channels": {
            "$ref": "#/components/schemas/Channels"
          },
          "size": {
            "$ref": "#/components/schemas/Size"
          },
          "crop": {
            "type": "boolean",
            "default": false,
            "description": "Crop transparent padding from the output."
          },
          "despill": {
            "type": "boolean",
            "default": false,
            "description": "Apply green-screen despill cleanup."
          },
          "bg_color": {
            "$ref": "#/components/schemas/BackgroundColor"
          },
          "bg_fit": {
            "$ref": "#/components/schemas/BackgroundFit"
          },
          "bg_position": {
            "$ref": "#/components/schemas/BackgroundPosition"
          }
        }
      },
      "OutputFormat": {
        "type": "string",
        "enum": [
          "png",
          "jpg",
          "jpeg",
          "jpe",
          "jfif",
          "webp",
          "bmp",
          "tiff",
          "tif",
          "gif"
        ],
        "default": "png",
        "description": "Output image format. jpeg, jpe, and jfif are aliases for jpg; tif is an alias for tiff. JSON requests with channels=rgba are returned as JPEG regardless of this option."
      },
      "Channels": {
        "type": "string",
        "enum": [
          "rgba",
          "alpha"
        ],
        "default": "rgba",
        "description": "rgba returns a cutout image. alpha returns a PNG alpha mask."
      },
      "Size": {
        "type": "string",
        "enum": [
          "preview",
          "medium",
          "hd",
          "full",
          "auto"
        ],
        "default": "full",
        "description": "Output size target. preview is about 0.25 MP, medium about 1.5 MP, hd about 4 MP, and full or auto preserves up to the service limit."
      },
      "BackgroundColor": {
        "type": [
          "string",
          "null"
        ],
        "default": null,
        "examples": [
          "#ffffff",
          "white",
          "transparent"
        ],
        "description": "Optional solid background color. Six-digit hex, three-digit hex, and Pillow-supported named colors are accepted."
      },
      "BackgroundFit": {
        "type": "string",
        "enum": [
          "cover",
          "contain",
          "stretch"
        ],
        "default": "cover",
        "description": "How a background image is fit to the output canvas."
      },
      "BackgroundPosition": {
        "type": "string",
        "enum": [
          "center",
          "top",
          "bottom",
          "left",
          "right",
          "top-left",
          "top-right",
          "bottom-left",
          "bottom-right"
        ],
        "default": "center",
        "description": "Position for cover or contain background image placement."
      },
      "ProcessedImageJsonResponse": {
        "type": "object",
        "required": [
          "image",
          "mime",
          "width",
          "height"
        ],
        "properties": {
          "image": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Base64-encoded processed image."
          },
          "mime": {
            "type": "string",
            "example": "image/jpeg"
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "AlphaMaskJsonResponse": {
        "type": "object",
        "required": [
          "mask",
          "mime",
          "width",
          "height"
        ],
        "properties": {
          "mask": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Base64-encoded PNG alpha mask."
          },
          "mime": {
            "type": "string",
            "const": "image/png"
          },
          "width": {
            "type": "integer",
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "AccountResponse": {
        "type": "object",
        "required": [
          "status",
          "api_key",
          "account"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          },
          "api_key": {
            "type": "object",
            "required": [
              "valid",
              "mode",
              "fingerprint"
            ],
            "properties": {
              "valid": {
                "type": "boolean",
                "const": true
              },
              "mode": {
                "type": "string",
                "example": "live",
                "description": "Public key mode."
              },
              "fingerprint": {
                "type": "string",
                "pattern": "^tok_fp_[0-9a-f]{12}$"
              }
            }
          },
          "account": {
            "type": "object",
            "required": [
              "email",
              "plan",
              "subscription_status",
              "billing_model",
              "usage_unit"
            ],
            "properties": {
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "email"
              },
              "plan": {
                "type": "string",
                "example": "Business"
              },
              "subscription_status": {
                "type": "string",
                "example": "active"
              },
              "billing_model": {
                "type": "string",
                "example": "metered_monthly"
              },
              "usage_unit": {
                "type": "string",
                "example": "image"
              }
            }
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "examples": [
                  "missing_api_key",
                  "invalid_api_key",
                  "invalid_image",
                  "payload_too_large"
                ]
              },
              "message": {
                "type": "string"
              },
              "status": {
                "type": "integer"
              },
              "request_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "responses": {
      "HealthOk": {
        "description": "The service is healthy.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/HealthResponse"
            },
            "example": {
              "status": "ok"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request body, parameters, image input, or processing option.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "invalid_image",
                "message": "body is not a valid image",
                "status": 400,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, or revoked API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "invalid_api_key",
                "message": "Invalid or revoked API key.",
                "status": 401,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key is recognized but not allowed to perform this request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "Forbidden.",
                "status": 403,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The uploaded image or decoded image exceeds service limits.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "payload_too_large",
                "message": "image too large (>30 MB).",
                "status": 413,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Unsupported request media type.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "unsupported_media_type",
                "message": "Unsupported media type.",
                "status": 415,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "Request validation failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "Request validation failed.",
                "status": 422,
                "request_id": "0d4f5484ef544c58935c79064d3980b8",
                "details": {}
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "The request was rate limited.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limited.",
                "status": 429,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ProcessingFailed": {
        "description": "Image processing failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "processing_failed",
                "message": "Image processing failed.",
                "status": 502,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The image processing service is temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "processing_unavailable",
                "message": "Image processing service is temporarily unavailable.",
                "status": 503,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      },
      "Timeout": {
        "description": "The request timed out while processing the image.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "timeout",
                "message": "Request timed out.",
                "status": 504,
                "request_id": "0d4f5484ef544c58935c79064d3980b8"
              }
            }
          }
        }
      }
    }
  }
}