How to Filter and Customize Cat Images from the CATAAS API

You can filter and customize CATAAS cat images with query parameters on the /cat endpoint: type sets the image shape (xsmall, small, medium, square), filter applies blur, mono, negate, or custom effects, width/height resize the image, and filter=custom accepts brightness, lightness, saturation, hue, or RGB values. All of these can be combined with tag paths and the says text endpoint, so a single request can return, for example, a square, monochrome, resized cat saying "Hello."

The parameters at a glance

These are documented as query parameters on /cat, so they attach after a ? and are joined with &.

Step-by-step: build a customized request

1. Start from the base endpoint. A plain GET /cat returns a random cat.
2. Add a shape if you need one. GET /cat?type=square returns a square cat; the other documented values are xsmall, small, and medium.
3. Add a filter. GET /cat?filter=mono returns a monochrome cat. The presets are blur, mono, and negate.
4. Or tune the filter yourself. GET /cat?filter=custom&brightness=:brightness&lightness=:lightness&saturation=:saturation&hue=:hue adjusts those four properties, while GET /cat?filter=custom&r=:red&g=:green&b=:blue applies an RGB filter.
5. Resize. GET /cat?width=:width or GET /cat?height=:height returns the cat at your chosen dimension.
6. Combine everything. The documentation's own combo example is /cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square, which mixes a GIF, overlay text, a filter, text styling, and an image type in one request.

Expected result: the response is the image itself, unless you ask for another format (see below). Verify it worked by checking that the returned image shows the shape, filter, and size you requested; if a parameter seems ignored, confirm the spelling and that it is attached to /cat with ? and &.

Combining filters with tags and text

Filters are query parameters, so they stack on top of the path-based features:

• Tags: /cat/:tag returns a random cat with that tag, and multiple tags can be combined with the :tag separator (the docs show "Random orange cute cat" as the example). Add filters after the path, e.g. /cat/:tag?filter=blur.
• Text overlay: /cat/says/:text returns a cat saying your text, and /cat/:tag/says/:text combines a tag with text. Text styling is also available via fontSize and fontColor, as in /cat/says/:text?fontSize=:size&fontColor=:color.
• Everything at once: a tag path, says, and query filters can all appear in one URL, following the combo pattern above.

Choosing between presets and custom filters

• Use a preset (blur, mono, negate) when you want a predictable, one-word effect and don't need fine control — it keeps URLs short and readable.
• Use filter=custom when you need a specific look: the brightness/lightness/saturation/hue route for perceptual adjustments, or the r/g/b route for color-channel control. Note that the two custom forms are documented separately, so pick one per request rather than assuming they merge.
• Use type vs. width/height depending on intent: type selects a documented image variant, while width/height gives you an explicit dimension. If you need an exact pixel size, the width/height parameters are the direct route.

Getting JSON instead of an image

If your client needs metadata rather than the binary image, the docs describe two options: /cat?json=true returns a random cat as a JSON object, and the newer behavior returns JSON when the request contains an application/json header. For browsing the collection, /api/cats?tags=tag1,tag2&skip=0&limit=10 returns cats filtered by tags with pagination, and /api/tags returns all available tags — useful for discovering valid tag values before building filtered image URLs.

Common snags

• Tag search behavior changed: the site notes a fix for tags search and for tags combined with a , separator, so if you relied on older tag syntax, check the current API doc.
• Mixing parameters: keep the ?/& structure intact when combining filter, type, and text options; a malformed query is the most likely reason a customization silently doesn't apply.
• JSON vs. image: decide up front whether you want the image or the JSON object, since json=true or the JSON header changes the response type.