Search Icons8 illustrations - the ONLY source for genuine Icons8 illustrations.
Illustrations are full scenes with people, objects and backgrounds. Reach
for one when a page needs a hero image, an empty state, an onboarding
step or a spot illustration. For a small symbol in a button, a menu or a
table, use search_icons instead.
Every result carries `preview.url`: a permanent CDN link (webp) you can
embed directly. It never expires and needs no second call. Use
get_illustration_svg or get_illustration_png_url only when you need the
original asset rather than a preview.
Some illustrations are animated. A result says so in `media_types`, and
almost all of those carry an `animation` block: `webm` and `mov` play
the animation, `poster` is the still frame. They are previews - see
below for what that costs - and get_illustration_animation is what
returns a file to publish, along with the <video> markup to publish it
with.
`animation.lottie` says whether a Lottie JSON exists for this
illustration, so you need not spend a call to find out. It is worth
checking: Lottie is missing from most work added since 2024, and two
illustrations in the same style often disagree about it. When it is
false, do not ask get_illustration_animation for "lottie".
MIND THE SIZE, AND READ IT FROM THE BLOCK. The animation links are
previews, 368x368 - fine for a spot, a card or a list row, too small for
a hero banner or a full-width section. Do not infer the size from
`preview`: the still preview is not square for about a third of
illustrations, while the animation always is. When the slot is large,
use `poster` (1200x1200, a still) or call get_illustration_animation for
the full-size video.
THE ANIMATION LINKS ARE FOR CHOOSING, NOT FOR SHIPPING. Two limits, and
both are invisible until the page is built:
- No transparency. `webm` and `mov` here are flat against an opaque
#F7F7F7, and the preview `mov` carries no alpha layer at all. On a
coloured or dark section they render as a light-grey rectangle; on a
hero they are 368px. Only `poster` is transparent.
- A watermark, unless the account is entitled to the illustration.
`animation.watermarked` says which you got, for these links, in this
response: false means "Icons8 Ouch" is not tiled across the frame.
It is false for a subscriber, and for anything with
`free_distribution: true` whoever asks. It says nothing about the
size or the transparency above, which apply either way.
Use them to pick an illustration, and `poster` where a still will do.
For anything that ships, call get_illustration_animation and host the
file: it is full size, transparent, and never watermarked.
A few animated illustrations carry no `animation` block at all, so read
the block, do not assume it.
SEARCH TIPS:
- Describe the scene, not the symbol: "team meeting", "online payment"
- One or two words work better than a sentence
- Pass `style` to keep a whole project on one visual family - get the
available values from list_illustrations_styles
- Pass `category` to narrow a broad word - "cat" alone returns over a
thousand hits; in category "animal" it returns far fewer, and in
"business" fewer still. Values come from list_illustrations_categories
- Pass free_only=True for illustrations a free Icons8 account can use
ABOUT `free_distribution` IN THE RESULTS - do not warn the user about
licensing based on it:
- true means the illustration is available on a free Icons8 account and
free to redistribute: the user may use and share it without a
licence. Ouch skips the entitlement check for these and does not
count them against a subscriber's allowance
- false means it needs a paid account. For a subscriber that is the
ordinary case - available, and counted against their allowance. It
does NOT mean *this* user cannot have it, and it does NOT mean some
second licence beyond their subscription is required
Whether this user may download something is decided by the download
call, not by this flag. Ask for the asset; if it is refused, the error
says exactly what is missing. Never turn `free_distribution: false` into
a licence warning of your own.
Args:
query: What the illustration should show (max 150 characters)
ctx: MCP context for API access
style: Optional style pretty_id from list_illustrations_styles
category: Optional category pretty_id from list_illustrations_categories
free_only: Only illustrations a free Icons8 account can use and
redistribute without a licence
animated: True for animated only, False for static only. Nearly every
animated result carries an `animation` block - permanent WebM and
HEVC links you can embed directly, plus a poster frame - but a
few carry none, and some carry the poster without the video, so
check the block rather than assuming its keys. For the full-size
original, use get_illustration_animation.
amount: Results per page (default: 10, max: 100)
page: Page number, 1-based (this API paginates by page, not offset)
Returns:
{"total", "illustrations"}, each entry carrying id, heading, styles,
tags, media_types and a permanent preview link - plus an `animation`
block when media_types includes "animated" - or {"error"}
