{
  "openapi": "3.0.3",
  "info": {
    "title": "Background Removal API — Cutouts & Masks",
    "version": "0.1.0",
    "description": "Callable Labs public endpoint reference. Obtain the base URL and credentials from the marketplace listing. Availability can differ by marketplace."
  },
  "paths": {
    "/v1/background/remove": {
      "post": {
        "tags": [
          "Remove backgrounds"
        ],
        "summary": "Remove the background",
        "description": "Send one photo by URL, base64 or file upload. `format: json` (default) returns a\nPNG data URI plus the size, the subject's bounding box and how much of the image\nit covers; `png`, `webp` and `jpeg` return the image bytes.\n\n`background` is `transparent` or a colour such as `#FFFFFF` (JPEG needs a colour).\n`crop: true` trims to the subject, with `padding` pixels around it; `max_size` sets\nthe longest side of the output. Choose `quality: best` for detail or `fast` for previews.\n\n**More examples**\n\n*Transparent PNG file*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg\"\n  },\n  \"format\": \"png\"\n}\n```\n\n*Product photo on white, cropped (JPEG)*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg\"\n  },\n  \"format\": \"jpeg\",\n  \"background\": \"#FFFFFF\",\n  \"crop\": true,\n  \"padding\": 40\n}\n```\n\n*Fast WebP thumbnail*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg\"\n  },\n  \"format\": \"webp\",\n  \"quality\": \"fast\",\n  \"max_size\": 512\n}\n```",
        "operationId": "Remove background",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveRequest"
              },
              "example": {
                "image": {
                  "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
                },
                "format": "json"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image (PNG, JPEG, WebP, GIF, BMP or TIFF; ≤ 20 MB)"
                  },
                  "crop": {
                    "type": "boolean",
                    "description": "Crop the result to the subject's bounding box.",
                    "default": false
                  },
                  "padding": {
                    "type": "integer",
                    "maximum": 1000,
                    "minimum": 0,
                    "description": "Pixels kept around the subject when `crop` is true.",
                    "default": 0
                  },
                  "max_size": {
                    "type": "integer",
                    "maximum": 4096,
                    "minimum": 64,
                    "description": "Longest side of the output in pixels (default: original, at most 4096)."
                  },
                  "quality": {
                    "type": "string",
                    "enum": [
                      "best",
                      "fast"
                    ],
                    "description": "best (default) prioritizes detail; fast is suitable for previews. Compare both on your own images.",
                    "default": "best"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "png",
                      "webp",
                      "jpeg"
                    ],
                    "description": "`json` returns metadata plus a PNG data URI; `png`/`webp` return the image bytes; `jpeg` needs an opaque `background`.",
                    "default": "json"
                  },
                  "background": {
                    "type": "string",
                    "pattern": "^(transparent|#[0-9A-Fa-f]{6})$",
                    "description": "`transparent`, or a colour `#RRGGBB` to place the subject on.",
                    "default": "transparent",
                    "example": "transparent"
                  }
                },
                "type": "object",
                "required": [
                  "file"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The result: JSON (metadata + PNG data URI) or the image bytes, per `format`",
            "headers": {
              "X-Subject-BBox": {
                "description": "x,y,width,height of the subject in the original image",
                "schema": {
                  "type": "string"
                }
              },
              "X-Foreground-Ratio": {
                "description": "Share of the image covered by the subject",
                "schema": {
                  "type": "number"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              },
              "image/png": {},
              "image/webp": {},
              "image/jpeg": {}
            }
          },
          "401": {
            "description": "Authentication failed. Verify the RapidAPI subscription and generated request headers."
          },
          "413": {
            "description": "The request body exceeds the configured gateway or endpoint limit."
          },
          "422": {
            "description": "`invalid_request`: a field failed the schema (`errors[].loc` names it), e.g. `jpeg` with a transparent background. `bad_image`: not a decodable image. `image_too_large`: over 40 megapixels. `file_too_large`: over 20 MB. `invalid_url`, `url_unreachable`, `private_address_blocked`, `invalid_base64`: the image could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "The subscriber's rate limit or monthly request allowance was exceeded."
          },
          "502": {
            "description": "Processing failed temporarily. Retry with bounded backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The service is busy or temporarily unavailable. Honor Retry-After and use bounded retries.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Processing exceeded the time limit. Try a smaller or simpler input if the error repeats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/background/mask": {
      "post": {
        "tags": [
          "Remove backgrounds"
        ],
        "summary": "Get the subject mask",
        "description": "The 8-bit alpha mask (white = subject) at the original size, or cropped and resized\nlike the cutout — for your own compositing, blurring or effects. Each mask or\ncutout request counts separately toward your allowance.\n\n**More examples**\n\n*Mask as a PNG file*\n\n```json\n{\n  \"image\": {\n    \"url\": \"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg\"\n  },\n  \"format\": \"png\"\n}\n```",
        "operationId": "Get mask",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MaskRequest"
              },
              "example": {
                "image": {
                  "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
                },
                "format": "json"
              }
            },
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image (PNG, JPEG, WebP, GIF, BMP or TIFF; ≤ 20 MB)"
                  },
                  "crop": {
                    "type": "boolean",
                    "description": "Crop the result to the subject's bounding box.",
                    "default": false
                  },
                  "padding": {
                    "type": "integer",
                    "maximum": 1000,
                    "minimum": 0,
                    "description": "Pixels kept around the subject when `crop` is true.",
                    "default": 0
                  },
                  "max_size": {
                    "type": "integer",
                    "maximum": 4096,
                    "minimum": 64,
                    "description": "Longest side of the output in pixels (default: original, at most 4096)."
                  },
                  "quality": {
                    "type": "string",
                    "enum": [
                      "best",
                      "fast"
                    ],
                    "description": "best (default) prioritizes detail; fast is suitable for previews. Compare both on your own images.",
                    "default": "best"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "png"
                    ],
                    "description": "`json` returns metadata plus a PNG data URI; `png` returns the 8-bit grayscale mask.",
                    "default": "json"
                  }
                },
                "type": "object",
                "required": [
                  "file"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The result: JSON (metadata + PNG data URI) or the image bytes, per `format`",
            "headers": {
              "X-Subject-BBox": {
                "description": "x,y,width,height of the subject in the original image",
                "schema": {
                  "type": "string"
                }
              },
              "X-Foreground-Ratio": {
                "description": "Share of the image covered by the subject",
                "schema": {
                  "type": "number"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              },
              "image/png": {}
            }
          },
          "401": {
            "description": "Authentication failed. Verify the RapidAPI subscription and generated request headers."
          },
          "413": {
            "description": "The request body exceeds the configured gateway or endpoint limit."
          },
          "422": {
            "description": "`invalid_request`: a field failed the schema (`errors[].loc` names it), e.g. `jpeg` with a transparent background. `bad_image`: not a decodable image. `image_too_large`: over 40 megapixels. `file_too_large`: over 20 MB. `invalid_url`, `url_unreachable`, `private_address_blocked`, `invalid_base64`: the image could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "The subscriber's rate limit or monthly request allowance was exceeded."
          },
          "502": {
            "description": "Processing failed temporarily. Retry with bounded backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The service is busy or temporarily unavailable. Honor Retry-After and use bounded retries.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Processing exceeded the time limit. Try a smaller or simpler input if the error repeats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RemoveRequest": {
        "additionalProperties": false,
        "properties": {
          "crop": {
            "default": false,
            "description": "Crop the result to the subject's bounding box.",
            "title": "Crop",
            "type": "boolean"
          },
          "padding": {
            "default": 0,
            "description": "Pixels kept around the subject when `crop` is true.",
            "maximum": 1000,
            "minimum": 0,
            "title": "Padding",
            "type": "integer"
          },
          "max_size": {
            "maximum": 4096,
            "minimum": 64,
            "type": "integer",
            "nullable": true,
            "title": "Max Size",
            "description": "Longest side of the output in pixels (default: original, at most 4096).",
            "default": null
          },
          "quality": {
            "default": "best",
            "description": "best (default) prioritizes detail; fast is suitable for previews. Compare both on your own images.",
            "enum": [
              "best",
              "fast"
            ],
            "title": "Quality",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "`json` returns metadata plus a PNG data URI; `png`/`webp` return the image bytes; `jpeg` needs an opaque `background`.",
            "enum": [
              "json",
              "png",
              "webp",
              "jpeg"
            ],
            "title": "Format",
            "type": "string"
          },
          "background": {
            "default": "transparent",
            "description": "`transparent`, or a colour `#RRGGBB` to place the subject on.",
            "pattern": "^(transparent|#[0-9A-Fa-f]{6})$",
            "title": "Background",
            "type": "string",
            "example": "transparent"
          },
          "image": {
            "$ref": "#/components/schemas/ImageSource"
          }
        },
        "required": [
          "image"
        ],
        "title": "RemoveRequest",
        "type": "object"
      },
      "ImageSource": {
        "additionalProperties": false,
        "properties": {
          "url": {
            "maxLength": 2048,
            "type": "string",
            "nullable": true,
            "title": "Url",
            "description": "Public http(s) URL of the image (≤ 20 MB). Private and internal addresses are refused.",
            "default": null,
            "example": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
          },
          "base64": {
            "maxLength": 27962090,
            "type": "string",
            "nullable": true,
            "title": "Base64",
            "description": "The image as base64 (a `data:` URI is fine), ≤ 20 MB decoded.",
            "default": null
          }
        },
        "title": "ImageSource",
        "type": "object"
      },
      "Result": {
        "properties": {
          "format": {
            "description": "Encoding of `data_uri`",
            "title": "Format",
            "type": "string"
          },
          "media_type": {
            "title": "Media Type",
            "type": "string"
          },
          "width": {
            "description": "Output width in pixels",
            "title": "Width",
            "type": "integer"
          },
          "height": {
            "description": "Output height in pixels",
            "title": "Height",
            "type": "integer"
          },
          "bytes": {
            "title": "Bytes",
            "type": "integer"
          },
          "data_uri": {
            "description": "`data:<media_type>;base64,…`",
            "title": "Data Uri",
            "type": "string"
          },
          "bbox": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BBox"
              }
            ],
            "nullable": true,
            "description": "Subject bounding box in the original image (null when nothing was found)"
          },
          "foreground_ratio": {
            "description": "Share of the original image covered by the subject (0–1)",
            "title": "Foreground Ratio",
            "type": "number"
          },
          "quality": {
            "enum": [
              "best",
              "fast"
            ],
            "title": "Quality",
            "type": "string",
            "description": "best (default) prioritizes detail; fast is suitable for previews. Compare both on your own images."
          }
        },
        "required": [
          "format",
          "media_type",
          "width",
          "height",
          "bytes",
          "data_uri",
          "bbox",
          "foreground_ratio",
          "quality"
        ],
        "title": "Result",
        "type": "object",
        "additionalProperties": true
      },
      "BBox": {
        "properties": {
          "x": {
            "title": "X",
            "type": "integer"
          },
          "y": {
            "title": "Y",
            "type": "integer"
          },
          "width": {
            "title": "Width",
            "type": "integer"
          },
          "height": {
            "title": "Height",
            "type": "integer"
          }
        },
        "required": [
          "x",
          "y",
          "width",
          "height"
        ],
        "title": "BBox",
        "type": "object"
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable failure code"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation"
              },
              "errors": {
                "type": "array",
                "description": "Per-field or per-line detail when there is more than one thing to fix",
                "items": {
                  "type": "object",
                  "properties": {
                    "loc": {
                      "type": "string",
                      "description": "Field path, e.g. `body.scale`"
                    },
                    "line": {
                      "type": "integer"
                    },
                    "column": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "additionalProperties": true
          }
        }
      },
      "MaskRequest": {
        "additionalProperties": false,
        "properties": {
          "crop": {
            "default": false,
            "description": "Crop the result to the subject's bounding box.",
            "title": "Crop",
            "type": "boolean"
          },
          "padding": {
            "default": 0,
            "description": "Pixels kept around the subject when `crop` is true.",
            "maximum": 1000,
            "minimum": 0,
            "title": "Padding",
            "type": "integer"
          },
          "max_size": {
            "maximum": 4096,
            "minimum": 64,
            "type": "integer",
            "nullable": true,
            "title": "Max Size",
            "description": "Longest side of the output in pixels (default: original, at most 4096).",
            "default": null
          },
          "quality": {
            "default": "best",
            "description": "best (default) prioritizes detail; fast is suitable for previews. Compare both on your own images.",
            "enum": [
              "best",
              "fast"
            ],
            "title": "Quality",
            "type": "string"
          },
          "format": {
            "default": "json",
            "description": "`json` returns metadata plus a PNG data URI; `png` returns the 8-bit grayscale mask.",
            "enum": [
              "json",
              "png"
            ],
            "title": "Format",
            "type": "string"
          },
          "image": {
            "$ref": "#/components/schemas/ImageSource"
          }
        },
        "required": [
          "image"
        ],
        "title": "MaskRequest",
        "type": "object"
      }
    }
  }
}