{
  "openapi": "3.1.0",
  "info": {
    "title": "Poof API",
    "description": "The developer-first standard for background removal. Precise, fast, and scalable.",
    "version": "1.0.0",
    "contact": {
      "name": "Poof Support",
      "email": "support@poof.bg",
      "url": "https://poof.bg"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://poof.bg/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.poof.bg/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/remove": {
      "post": {
        "operationId": "removeBackground",
        "summary": "Remove Background",
        "description": "Remove the background from an image or a video. The media type is detected from the file content, never from the field name or extension. Images are processed synchronously and returned directly in the response body (200); each successful image request costs 1 credit regardless of parameters. Videos are accepted with 202 and processed in the background: poll GET /jobs/{id} every 2 to 5 seconds and download the job's result_url (a direct CDN link, valid for 24 hours) once it is completed. Video costs 5 credits per second of source video, rounded up (10 per second above 30 fps), charged on acceptance and refunded automatically if the job fails. Animated GIF input is billed at 5 credits per second whatever its frame rate. Video limits: 5 minutes, 100 MB upload or 500 MB via url, output up to 4K (4096 px on the longest side), audio preserved except with channels=alpha. 4K files are large, so pass a url (up to 500 MB) rather than uploading; 4K jobs take about 1.5 times as long as 1080p ones. An animated GIF (two or more frames) is a video; a still GIF is handled by the image path and an animated WebP uses its first frame. GIF output is capped at 1280 px on the longest side (720p for widescreen) and 50 fps. Failed and rejected requests are not billed.",
        "tags": ["Background Removal"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image or video to process. Images: JPEG, PNG, WebP or a still GIF, max 20MB. Videos: MP4, MOV, WebM, M4V, MKV or an animated GIF, max 100MB (use url for larger files). Required unless url is given. The legacy names image_file and image_file_b64 are accepted as aliases."
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://example.com/photos/product.jpg",
                    "description": "Public https URL of the image or video to process (an animated GIF counts as a video); Poof downloads it server-side (images max 20MB, videos max 500MB, up to 3 redirects, 15s timeout). URLs pointing at private, loopback or link-local addresses are rejected. If the download fails (the server answers with an HTTP error, times out, cannot be reached or redirects too often), the request is rejected with 400 validation_error and details.field set to \"url\" (or \"image_url\" when the alias was used); for an HTTP error, details.status carries the upstream status code. Required unless file is given. The legacy name image_url is accepted as an alias."
                  },
                  "image_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Legacy alias for file. Behaves exactly like file, for images and videos alike."
                  },
                  "image_file_b64": {
                    "type": "string",
                    "format": "byte",
                    "description": "Legacy alias: the image as a base64 string, with or without a data:<mime>;base64, prefix. Max 20MB decoded. Images only."
                  },
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Legacy alias for url. Behaves exactly like url."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["png", "jpg", "webp", "webm", "mov", "mp4", "gif"],
                    "description": "Output format. Images: png (default), jpg or webp; for remove.bg compatibility, auto is accepted and treated as png, zip is not supported. Videos: webm (default, VP9, transparent with channels=rgba and no bg_color), mov (ProRes, transparent with channels=rgba and no bg_color), mp4 (H.264, never transparent: the subject is composited on bg_color, white by default) or gif (looping, 1-bit transparency with channels=rgba and no bg_color, otherwise composited on bg_color, no audio, capped at 1280 px on the longest side (720p for widescreen) and 50 fps whatever size says). A format from the wrong family for the media is rejected with 400 validation_error listing the valid values."
                  },
                  "channels": {
                    "type": "string",
                    "enum": ["rgba", "rgb", "alpha"],
                    "default": "rgba",
                    "description": "Output color channels. Use 'rgba' for transparency (setting bg_color fills the background instead), 'rgb' for an opaque output (background filled with bg_color, white by default), or 'alpha' for the grayscale alpha mask only (for video: a grayscale matte video with no audio track)."
                  },
                  "bg_color": {
                    "type": "string",
                    "description": "Background color (hex, rgb or color name). Setting it fills the background, so the result is opaque on that color, for images and videos in every format (webm, mov and gif included). Without it, channels=rgba output stays transparent where the format supports it, while channels=rgb, format=jpg and format=mp4 are opaque on white. Ignored with channels=alpha.",
                    "example": "#ffffff"
                  },
                  "size": {
                    "type": "string",
                    "enum": ["full", "preview", "medium", "hd"],
                    "default": "full",
                    "description": "Output size preset, for images and videos. Images: a megapixel cap, ignored when width or height is set. Videos: a cap on the longest side of every frame, aspect ratio kept: preview 640 px, medium 1280 px, hd 1920 px (1080p), full (default) the source resolution up to 4096 px (4K). For remove.bg compatibility the aliases auto, 4k and 50MP (treated as full) and small and regular (treated as preview) are also accepted."
                  },
                  "crop": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "string",
                        "pattern": "^\\d+:\\d+$"
                      }
                    ],
                    "default": false,
                    "description": "Image only (400 validation_error when sent with a video). Crop the image to the subject bounds. Pass true/false or an aspect ratio like '1:1', '4:3', '16:9'."
                  },
                  "padding": {
                    "type": "string",
                    "description": "Image only (400 validation_error when sent with a video). Padding around the subject when crop is enabled, added to each side as a fraction (e.g. '0.1') or percentage (e.g. '10%') of the subject's size on that axis. Pass one value for both axes, or two comma-separated values as horizontal,vertical (e.g. '10%,7.5%' gives a canvas 120% of subject width and 115% of subject height). Default '10%'.",
                    "example": "10%"
                  },
                  "crop_margin": {
                    "type": "string",
                    "example": "10%",
                    "description": "Image only (400 validation_error when sent with a video). remove.bg-compatible alias for padding, using CSS margin shorthand with one to four space-separated values (e.g. '10%' or '0px 5%'). Percentages map onto padding; a zero pixel margin means a tight crop; other pixel margins cannot be honoured and are ignored. Ignored when padding is set."
                  },
                  "width": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6000,
                    "example": 500,
                    "description": "Image only (400 validation_error when sent with a video). Output width in pixels (1-6000). On its own, the height follows the image's aspect ratio. Together with height, the image is fitted into a width x height canvas according to fit. The aspect ratio is always preserved (never stretched); smaller images are upscaled unless fit is 'scale-down'. Overrides size."
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6000,
                    "example": 500,
                    "description": "Image only (400 validation_error when sent with a video). Output height in pixels (1-6000). On its own, the width follows the image's aspect ratio. Together with width, the image is fitted into a width x height canvas according to fit. The aspect ratio is always preserved (never stretched); smaller images are upscaled unless fit is 'scale-down'. Overrides size."
                  },
                  "fit": {
                    "type": "string",
                    "enum": ["contain", "cover", "scale-down"],
                    "default": "contain",
                    "description": "Image only (400 validation_error when sent with a video). How to fit the image into width/height. 'contain' scales the image to fit inside and centres it, filling the remaining area with transparency (or bg_color). 'cover' scales the image to fill the canvas and crops the overflow, keeping the subject centred. 'scale-down' is like 'contain' but never enlarges: a smaller image keeps its native size (centred on the canvas when both dimensions are set). contain and cover only differ when both width and height are set."
                  }
                },
                "description": "Provide exactly one input: file (upload) or url (public https URL). The legacy names image_file, image_file_b64 and image_url are still accepted. If several are sent, file / image_file wins, then image_file_b64, then url / image_url. The media type is detected from the content; crop, padding, crop_margin, width, height and fit are image-only."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully processed image (image input only)",
            "headers": {
              "Content-Type": {
                "description": "MIME type of the returned image",
                "schema": {
                  "type": "string",
                  "example": "image/png"
                }
              },
              "X-Request-ID": {
                "description": "Unique request identifier for support",
                "schema": {
                  "type": "string",
                  "example": "req_abc123xyz"
                }
              },
              "X-Processing-Time-Ms": {
                "description": "Processing time in milliseconds",
                "schema": {
                  "type": "integer",
                  "example": 450
                }
              },
              "X-Image-Width": {
                "description": "Output image width in pixels",
                "schema": {
                  "type": "integer",
                  "example": 1920
                }
              },
              "X-Image-Height": {
                "description": "Output image height in pixels",
                "schema": {
                  "type": "integer",
                  "example": 1080
                }
              },
              "X-Matte-Confidence": {
                "description": "Heuristic confidence in the alpha matte, 0-1. Mean decisiveness of the mask: 1 means fully binary, lower values mean the model hedged. Not a calibrated probability.",
                "schema": {
                  "type": "number",
                  "example": 0.9732
                }
              },
              "X-Matte-Ambiguous-Ratio": {
                "description": "Fraction of pixels with alpha between 0.1 and 0.9, 0-1. High values indicate large uncertain regions; useful for flagging results for review.",
                "schema": {
                  "type": "number",
                  "example": 0.0427
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "description": "Video accepted (video input only). The video has been probed, credits have been charged and processing has been queued. Poll GET /jobs/{id}.",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier for support",
                "schema": {
                  "type": "string",
                  "example": "req_abc123xyz"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8f3a1c2e9b7d4a10",
                  "status": "queued",
                  "progress": 0,
                  "created_at": "2026-10-12T10:12:00Z",
                  "started_at": null,
                  "completed_at": null,
                  "duration_seconds": 12.4,
                  "fps": 29.97,
                  "width": 1920,
                  "height": 1080,
                  "frames": 372,
                  "credits": 65,
                  "format": "webm",
                  "channels": "rgba",
                  "status_url": "https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10",
                  "result_url": null,
                  "expires_at": null,
                  "error": null,
                  "stats": null
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validation_error": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "validation_error",
                      "message": "Invalid value for 'format': expected one of png, jpg, webp.",
                      "details": {
                        "format": ["must be one of: png, jpg, webp"]
                      },
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/validation-error"
                    }
                  },
                  "missing_image": {
                    "summary": "Missing Image",
                    "value": {
                      "code": "missing_image",
                      "message": "No input provided. Send multipart/form-data with a 'file' part or a 'url' field.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/missing-image"
                    }
                  },
                  "image_too_large": {
                    "summary": "Image Too Large",
                    "value": {
                      "code": "image_too_large",
                      "message": "The uploaded image exceeds the 20 MB limit.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/image-too-large"
                    }
                  },
                  "validation_error_url_download": {
                    "summary": "The url could not be downloaded",
                    "value": {
                      "code": "validation_error",
                      "message": "url returned HTTP 404.",
                      "details": {
                        "field": "url",
                        "status": 404
                      },
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/validation-error"
                    }
                  },
                  "validation_error_video_field": {
                    "summary": "Image-only parameter sent with a video",
                    "value": {
                      "code": "validation_error",
                      "message": "'crop' is not supported for video.",
                      "details": {
                        "field": "crop"
                      },
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/validation-error"
                    }
                  },
                  "video_too_long": {
                    "summary": "Video Too Long",
                    "value": {
                      "code": "video_too_long",
                      "message": "The video is 7m 12s long. The maximum duration is 5 minutes.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/video-too-long"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "authentication_error",
                  "message": "API key missing or not recognised. Send it in the 'x-api-key' header.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/authentication-error"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required. The plan's monthly credits are used up, or (video) the clip costs more credits than are left in the billing cycle; then details.credits_required and details.credits_remaining are set and no job is created. The check covers one request at a time, so clips submitted at the same moment can together exceed the remaining credits.",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "payment_required",
                  "message": "Your plan's monthly credits are used up. Top up, enable Auto Recharge, upgrade, or wait for the cycle reset.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/payment-required"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "permission_denied",
                  "message": "This endpoint is not included in your current plan.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/permission-denied"
                }
              }
            }
          },
          "413": {
            "description": "Payload Too Large",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "image_too_large": {
                    "summary": "Image Too Large",
                    "value": {
                      "code": "image_too_large",
                      "message": "The uploaded image exceeds the 20 MB limit.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/image-too-large"
                    }
                  },
                  "video_too_large": {
                    "summary": "Video Too Large",
                    "value": {
                      "code": "video_too_large",
                      "message": "The uploaded video exceeds the 100 MB limit. Send videos up to 500 MB via url.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/video-too-large"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_image": {
                    "summary": "Invalid Image",
                    "value": {
                      "code": "invalid_image",
                      "message": "The file could not be decoded as PNG, JPEG, WebP or a still GIF.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/invalid-image"
                    }
                  },
                  "invalid_video": {
                    "summary": "Invalid Video",
                    "value": {
                      "code": "invalid_video",
                      "message": "The file could not be decoded as a video. Send MP4, MOV, WebM, M4V, MKV or an animated GIF.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/invalid-video"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "rate_limit_exceeded",
                  "message": "Rate limit exceeded for your plan. Retry with exponential backoff.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/rate-limit-exceeded"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "internal_server_error": {
                    "summary": "Internal Server Error",
                    "value": {
                      "code": "internal_server_error",
                      "message": "An unexpected error occurred. Please try again.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/internal-server-error"
                    }
                  },
                  "processing_failed": {
                    "summary": "Processing Failed",
                    "value": {
                      "code": "processing_failed",
                      "message": "The model could not process this image. Try a smaller image or a different format.",
                      "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                      "doc_url": "https://docs.poof.bg/errors/processing-failed"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "The processing service is unreachable. Retry with exponential backoff.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/upstream-error"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "The processing service is temporarily unavailable. Retry with exponential backoff.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/upstream-error"
                }
              }
            }
          },
          "504": {
            "description": "Gateway Timeout",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "The processing service timed out. Retry with exponential backoff.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/upstream-error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "operationId": "getJob",
        "summary": "Get Job",
        "description": "Returns the current state of a job created by POST /remove for a video: status (queued, processing, completed or failed), progress from 0 to 1, and once completed the result_url (a direct CDN link that needs no API key) and expires_at (24 hours after completion, after which the result is deleted). Free; GET requests under /jobs/ are exempt from the per-organisation rate limit. Poll every 2 to 5 seconds.",
        "tags": ["Background Removal"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Job ID returned by POST /remove for a video (starts with job_).",
            "schema": {
              "type": "string",
              "example": "job_8f3a1c2e9b7d4a10"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job state",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier for support",
                "schema": {
                  "type": "string",
                  "example": "req_abc123xyz"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "examples": {
                  "processing": {
                    "summary": "Processing",
                    "value": {
                      "id": "job_8f3a1c2e9b7d4a10",
                      "status": "processing",
                      "progress": 0.42,
                      "created_at": "2026-10-12T10:12:00Z",
                      "started_at": "2026-10-12T10:12:04Z",
                      "completed_at": null,
                      "duration_seconds": 12.4,
                      "fps": 29.97,
                      "width": 1920,
                      "height": 1080,
                      "frames": 372,
                      "credits": 65,
                      "format": "webm",
                      "channels": "rgba",
                      "status_url": "https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10",
                      "result_url": null,
                      "expires_at": null,
                      "error": null,
                      "stats": null
                    }
                  },
                  "completed": {
                    "summary": "Completed",
                    "value": {
                      "id": "job_8f3a1c2e9b7d4a10",
                      "status": "completed",
                      "progress": 1,
                      "created_at": "2026-10-12T10:12:00Z",
                      "started_at": "2026-10-12T10:12:04Z",
                      "completed_at": "2026-10-12T10:12:41Z",
                      "duration_seconds": 12.4,
                      "fps": 29.97,
                      "width": 1920,
                      "height": 1080,
                      "frames": 372,
                      "credits": 65,
                      "format": "webm",
                      "channels": "rgba",
                      "status_url": "https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10",
                      "result_url": "https://cdn.poof.bg/1d/jobs/job_8f3a1c2e9b7d4a10/result.webm",
                      "expires_at": "2026-10-13T10:12:41Z",
                      "error": null,
                      "stats": {
                        "output_width": 1920,
                        "output_height": 1080,
                        "processing_seconds": 37.2,
                        "matting_seconds": 28.9,
                        "decode_wait_seconds": 1.4,
                        "encode_wait_seconds": 3.1,
                        "scene_cuts": 2,
                        "output_bytes": 18734211
                      }
                    }
                  },
                  "failed": {
                    "summary": "Failed",
                    "value": {
                      "id": "job_8f3a1c2e9b7d4a10",
                      "status": "failed",
                      "progress": 0.42,
                      "created_at": "2026-10-12T10:12:00Z",
                      "started_at": "2026-10-12T10:12:04Z",
                      "completed_at": "2026-10-12T10:12:20Z",
                      "duration_seconds": 12.4,
                      "fps": 29.97,
                      "width": 1920,
                      "height": 1080,
                      "frames": 372,
                      "credits": 65,
                      "format": "webm",
                      "channels": "rgba",
                      "status_url": "https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10",
                      "result_url": null,
                      "expires_at": null,
                      "error": {
                        "code": "processing_failed",
                        "message": "The model or encoder failed on this video."
                      },
                      "stats": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "authentication_error",
                  "message": "API key missing or not recognised. Send it in the 'x-api-key' header.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/authentication-error"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "job_not_found",
                  "message": "No job with id 'job_8f3a1c2e9b7d4a10' was found, or it has expired.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/job-not-found"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "internal_server_error",
                  "message": "An unexpected error occurred. Please try again.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/internal-server-error"
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "upstream_error",
                  "message": "The processing service is unreachable. Retry with exponential backoff.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/upstream-error"
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Get Account Info",
        "description": "Returns information about the authenticated account including plan details and credit usage. This endpoint is free: it does not consume credits and is not rate limited.",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Account information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountInfo"
                },
                "example": {
                  "organizationId": "org_abc123",
                  "plan": "Pro",
                  "maxCredits": 2000,
                  "usedCredits": 1234,
                  "autoRechargeThreshold": 0.9
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "headers": {
              "X-Request-ID": {
                "description": "Unique request identifier, equal to request_id in the body. Include it when contacting support.",
                "schema": {
                  "type": "string",
                  "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "authentication_error",
                  "message": "API key missing or not recognised. Send it in the 'x-api-key' header.",
                  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
                  "doc_url": "https://docs.poof.bg/errors/authentication-error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your API key. Get one at https://dash.poof.bg"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Error body returned by every non-2xx response. The X-Request-ID response header equals request_id.",
        "required": ["code", "message", "request_id"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code",
            "enum": [
              "authentication_error",
              "permission_denied",
              "payment_required",
              "rate_limit_exceeded",
              "validation_error",
              "missing_image",
              "image_too_large",
              "invalid_image",
              "processing_failed",
              "upstream_error",
              "internal_server_error",
              "not_found",
              "video_too_large",
              "video_too_long",
              "invalid_video",
              "job_not_found"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "details": {
            "description": "Optional additional context. For validation_error this is an object mapping field names to a list of messages.",
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "string"
              }
            ]
          },
          "request_id": {
            "type": "string",
            "description": "Unique request ID for support (also sent as the X-Request-ID header)",
            "example": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42"
          },
          "doc_url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the documentation page for this error code",
            "example": "https://docs.poof.bg/errors/validation-error"
          }
        }
      },
      "AccountInfo": {
        "type": "object",
        "properties": {
          "organizationId": {
            "type": "string",
            "description": "Your organization ID"
          },
          "plan": {
            "type": "string",
            "description": "Current plan display name (e.g. \"Free\", \"Pro\")",
            "example": "Pro"
          },
          "maxCredits": {
            "type": "integer",
            "description": "Total credits available in billing cycle",
            "example": 2000
          },
          "usedCredits": {
            "type": "integer",
            "description": "Credits used in current billing cycle",
            "example": 1234
          },
          "autoRechargeThreshold": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 0.95,
            "description": "Fraction of the plan limit at which Auto Recharge triggers (e.g. 0.9 = 90%). Omitted when Auto Recharge is off.",
            "example": 0.9
          }
        },
        "required": ["organizationId", "plan", "maxCredits", "usedCredits"]
      },
      "Job": {
        "type": "object",
        "description": "A video background removal job, as returned with 202 by POST /remove and by GET /jobs/{id}.",
        "required": [
          "id",
          "status",
          "progress",
          "created_at",
          "started_at",
          "completed_at",
          "duration_seconds",
          "fps",
          "width",
          "height",
          "frames",
          "credits",
          "format",
          "channels",
          "status_url",
          "result_url",
          "expires_at",
          "error",
          "stats"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Job ID, prefixed with job_",
            "example": "job_8f3a1c2e9b7d4a10"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "processing", "completed", "failed"],
            "description": "Job state. queued and processing are transient; completed and failed are terminal.",
            "example": "processing"
          },
          "progress": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Fraction of the video processed so far, 0 to 1",
            "example": 0.42
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the job was accepted",
            "example": "2026-10-12T10:12:00Z"
          },
          "started_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When processing began; null while queued",
            "example": "2026-10-12T10:12:04Z"
          },
          "completed_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the job reached completed or failed; null until then",
            "example": null
          },
          "duration_seconds": {
            "type": "number",
            "description": "Source video duration in seconds",
            "example": 12.4
          },
          "fps": {
            "type": "number",
            "description": "Source frame rate",
            "example": 29.97
          },
          "width": {
            "type": "integer",
            "description": "Source video width in pixels",
            "example": 1920
          },
          "height": {
            "type": "integer",
            "description": "Source video height in pixels",
            "example": 1080
          },
          "frames": {
            "type": "integer",
            "description": "Number of frames in the source video",
            "example": 372
          },
          "credits": {
            "type": "integer",
            "description": "Credits charged for this job (5 per second of source video, rounded up; 10 per second above 30 fps). Animated GIF input is billed at 5 credits per second whatever its frame rate. Refunded automatically if the job fails.",
            "example": 65
          },
          "format": {
            "type": "string",
            "enum": ["webm", "mov", "mp4", "gif"],
            "description": "Requested output format",
            "example": "webm"
          },
          "channels": {
            "type": "string",
            "enum": ["rgba", "rgb", "alpha"],
            "description": "Requested output channels",
            "example": "rgba"
          },
          "status_url": {
            "type": "string",
            "format": "uri",
            "description": "URL of the job; GET it to poll for progress",
            "example": "https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10"
          },
          "result_url": {
            "type": ["string", "null"],
            "format": "uri",
            "description": "Direct download URL of the result on the Poof CDN (https://cdn.poof.bg/...). Needs no API key; anyone with the link can download the file until expires_at. Served with Content-Disposition: attachment; filename=result.<ext>. Null until the job is completed.",
            "example": null
          },
          "expires_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the result is deleted, 24 hours after completion; null until the job is completed. After this time result_url stops working and the job returns 404 job_not_found.",
            "example": null
          },
          "error": {
            "type": ["object", "null"],
            "description": "Set when status is failed, null otherwise",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code",
                "example": "processing_failed"
              },
              "message": {
                "type": "string",
                "description": "Human-readable description of the failure",
                "example": "The model or encoder failed on this video."
              }
            },
            "example": null
          },
          "stats": {
            "type": ["object", "null"],
            "additionalProperties": true,
            "description": "Processing statistics, set once the job is completed and null otherwise. output_width, output_height and processing_seconds are guaranteed (the output is capped at 4096 px on the longest side (4K), or smaller with size; width and height above are the source dimensions). Other keys are informational and may change.",
            "properties": {
              "output_width": {
                "type": "integer",
                "description": "Output width in pixels",
                "example": 1920
              },
              "output_height": {
                "type": "integer",
                "description": "Output height in pixels",
                "example": 1080
              },
              "processing_seconds": {
                "type": "number",
                "description": "Wall-clock processing time, from started_at to completed_at",
                "example": 37.2
              }
            },
            "example": null
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Background Removal",
      "description": "Background removal for images and video, and the jobs that video processing creates"
    },
    {
      "name": "Account",
      "description": "Account and billing information"
    }
  ],
  "externalDocs": {
    "description": "Poof API Documentation",
    "url": "https://docs.poof.bg"
  }
}
