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 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"}. id is what get_illustration_svg, get_illustration_png_url and get_illustration_animation take as illustration_id; it is the only way to get an illustration's id.