How to Get a Random Cat Image with Custom Text from CATAAS

Call https://cataas.com/cat/says/:text, replacing :text with the words you want on the image. The API returns a random cat photo with that text rendered on it. You can add a tag in the path (/cat/:tag/says/:text) to narrow the image pool, and append fontSize and fontColor query parameters to style the text. No API key or setup is described on the site — a plain HTTP GET is all the documentation shows.

The basic request

The simplest form is a single GET to the says endpoint:

https://cataas.com/cat/says/hello

Per the CATAAS documentation, this "will return a random cat saying :text." The response is the image itself, so you can drop the URL straight into an <img> tag, a browser address bar, or a fetch/requests call.

To control the text styling, add query parameters:

https://cataas.com/cat/says/hello?fontSize=40&fontColor=orange

• fontSize sets the text size.
• fontColor sets the text color.

The docs list both parameters on the /cat/says/:text route, so they apply to the plain says endpoint as well as the tagged variant.

Narrowing the image with tags

If you want a specific kind of cat behind the text, insert a tag before says:

https://cataas.com/cat/cute/says/hello

The documentation's own example is "Random cute cat saying hello." You can combine multiple tags using the : separator — the docs show :tag chaining and give "Random orange cute cat" as the example, so a request like /cat/orange:cute/says/hello follows the documented pattern.

To see which tags exist before you build a URL, call the tags endpoint:

https://cataas.com/api/tags

This "will return all tags," giving you the valid values to plug into the path.

Combining text with other image options

The says route accepts the same query options as the base /cat endpoint. The documentation's combo example is:

/cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square

That single URL requests a GIF cat, applies a monochrome filter, renders "Hello" in orange at size 20, and returns a square image. The options you can mix in:

For filter=custom, the docs list two variants: brightness/lightness/saturation/hue, or red/green/blue values. These are documented on /cat, and the combo example shows filters working alongside says.

Getting JSON instead of an image

By default the endpoint returns image bytes. If you need metadata — for example, to build a gallery or cache entries — request JSON:

https://cataas.com/cat?json=true

The docs note that JSON is returned "if request contain application/json header," and the changelog confirms this behavior in the current major version. For a list of cats rather than one random result, use:

https://cataas.com/api/cats?tags=tag1,tag2&skip=0&limit=10

This returns all matching cats with pagination via skip and limit. Note the docs show tags joined with a comma in this endpoint, while the image path uses : to combine tags — keep the two syntaxes separate.

Verifying it worked

Open the URL in a browser: you should see a cat photo with your text overlaid. If you requested ?json=true with an application/json header, you should get a JSON object instead of an image. If the text is missing, check that :text is URL-encoded (spaces as %20) and that you used /says/ in the path, not a query parameter.

Common snags

• Wrong tag separator. Combining tags in the path uses :, but the /api/cats list endpoint uses ,. Mixing them up returns unexpected or empty results.
• Expecting JSON by default. Without the application/json header (or json=true), you get image bytes, which will look like garbage if you try to parse them as JSON.
• Text with special characters. Encode spaces and symbols in :text; an unencoded space can break the path.
• Assuming a fixed image. Every call returns a random cat, so the same URL gives a different picture each time — cache the response if you need stability.

The site's homepage counter reads "Have 0 cats for now," which reflects the live count at the time of the page snapshot rather than a limit on requests; the documentation describes no quota or authentication requirement for these endpoints.