Validation Error

HTTP Status: 400

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

For validation errors, details is an object mapping each invalid field name to a list of messages.

Reasons and How to Fix

Invalid Parameter Value

A parameter has an invalid value that doesn’t match the expected options. Common issues:

format must be one of: png, jpg, webp for an image, or webm, mov, mp4, gif for a video. Sending a format from the wrong family (for example format=png with a video) returns this error with the valid values for that media
channels must be one of: rgba, rgb, alpha
size must be one of: full, preview, medium, hd
crop must be a boolean (true/false) or an aspect ratio like 1:1, 4:3, 16:9
padding must be a number (0.1) or percentage (10%), optionally as horizontal,vertical (10%,7.5%)

Image-only Parameter Sent with a Video

crop, padding, crop_margin, width, height and fit only apply to images. Sending any of them with a video is rejected, and details.field names the offending parameter. Use size to downscale a video.

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

URL Could Not Be Downloaded

When Poof cannot download the url you sent, the request is rejected with 400 validation_error and details.field is "url" (or "image_url" if you used the legacy alias). If the server answered with an HTTP error, details.status carries its status code. Nothing is billed.

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

The same error, without status, covers a download that timed out (15 s), a host that could not be reached, more than 3 redirects, or a URL pointing at a private, loopback or link-local address. Check that the URL is public over https and opens without cookies or login (signed URLs must not have expired), or upload the file with file instead.

Incorrect Data Types

Parameters must be the correct type.

# ❌ Wrong - crop should be boolean, not string
-F "crop=yes"

# ✅ Correct
-F "crop=true"

Non-multipart Body

The /remove endpoint only accepts multipart/form-data. A JSON or raw body is rejected.

# ❌ Wrong - JSON body
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"image": "..."}'

# ✅ Correct
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: pk_your_api_key" \
  -F "file=@photo.jpg"

Valid Parameter Reference

Parameter	Type	Valid Values
`file`	file	Image (JPEG, PNG, WebP or a still GIF, max 20 MB) or video (MP4, MOV, WebM, M4V, MKV or animated GIF, max 100 MB). Required unless `url` is given
`url`	string	Public `https` URL of an image (max 20 MB) or video (max 500 MB). Required unless `file` is given
`format`	string	Image: `png`, `jpg`, `webp`. Video: `webm`, `mov`, `mp4`, `gif`
`channels`	string	`rgba`, `rgb`, `alpha`
`bg_color`	string	Hex, RGB, or color name
`size`	string	`full`, `preview`, `medium`, `hd`
`crop`	boolean or string	`true`, `false`, or aspect ratio like `1:1`. Image only
`padding`	string	Number (`0.1`) or percentage (`10%`), optionally `horizontal,vertical`; only with `crop`. Image only
`width`, `height`	integer	`1`–`6000`. Image only
`fit`	string	`contain`, `cover`, `scale-down`. Image only

Getting Started

Video guides

API Reference

Validation Error

Reasons and How to Fix

Invalid Parameter Value

Image-only Parameter Sent with a Video

URL Could Not Be Downloaded

Incorrect Data Types

Non-multipart Body

Valid Parameter Reference

Need Help?

​Reasons and How to Fix

​Invalid Parameter Value

​Image-only Parameter Sent with a Video

​URL Could Not Be Downloaded

​Incorrect Data Types

​Non-multipart Body

​Valid Parameter Reference

​Need Help?

Reasons and How to Fix

Invalid Parameter Value

Image-only Parameter Sent with a Video

URL Could Not Be Downloaded

Incorrect Data Types

Non-multipart Body

Valid Parameter Reference

Need Help?