Component: image

The image component shows an image on the canvas, with an optional caption. It is display-only.


Component id	`canvas.image`
Version	`v1`
Action name	`canvas_show_image`
Interaction class	Lifecycle-only (no `submit` or `skip`)
Default placement	`safe-area-right`

Images come from two sources, both under your control:

Your Knowledge Base: you curate the exact set of images the PAL may show, and it picks one by id.
Websites you allowlist: the PAL passes an image URL it received during the conversation (typically from a tool result), and Tavus renders it only if the URL clears a safety floor and its host matches your allowlist.

By default only the Knowledge Base source exists. The compiled action has no URL argument at all, so the PAL cannot show an image from the open web or from your site; the URL argument appears only once you enable web with at least one allowlisted domain.

Configuration

Attaching the skill alone does not activate image. It stays inactive (no action is compiled, no error) until at least one image is curated in the skill config or web is enabled with at least one domain.

Curated Knowledge Base images

Add the images to your Knowledge Base

Upload each image with Create Document and wait for it to finish processing. Curating a document that is still processing is rejected, so poll Get Document (or use the callback) first.

Curate them on the PAL

Save the document ids you want the PAL to be able to show, each with an optional caption and an optional “when to show this” hint.

curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "config": {
      "components": {
        "image": {
          "images": [
            {
              "document_id": "d1234567890",
              "caption": "Aurora Desk in walnut",
              "prompt": "Show when the user asks what the desk looks like or asks about finishes."
            },
            {
              "document_id": "d2468101214",
              "caption": "Cable tray, underside detail",
              "prompt": "Show when the user asks about cable management."
            }
          ]
        }
      }
    }
  }'

Field	Type	Required	Description
`images`	array	✅	The curated images, at most 50. The component activates as soon as one usable entry is saved. Order is preserved and is the order the PAL sees.
`images[].document_id`	string	✅	A Knowledge Base document id, returned by Create Document. Validated when you save the config.
`images[].caption`	string	❌	The caption shown under the image, max 280 characters. Defaults to the description Tavus generates while processing the image, or the document name.
`images[].prompt`	string	❌	Your “when to show this image” hint, max 500 characters. Given to the PAL alongside the caption to help it choose; never shown to the user.
`enabled`	boolean	❌	Defaults to `true`. Set `false` to switch the component off without deleting your curated list.
`web`	object	❌	The second source: image URLs from websites you allowlist. See Web images.

Which documents can be curated

When you save the config, every document_id must:

Be accessible to the account that owns the PAL. Otherwise: 400, One or more document_ids are not accessible.
Have finished processing. Documents still being ingested are rejected with 400, One or more document_ids are not ready for display; curate them once processing completes.

At conversation create, Tavus additionally resolves each curated document to a displayable image. A document is skipped if it is not an image (a PDF, a website crawl, a spreadsheet) or if its processed image is unavailable. Skipped entries are simply absent from what the PAL can show; the rest of the curated list still works.

Web images

The web object lets the PAL show images it finds mid-conversation, typically URLs returned by a tool you built: a product search, a listing lookup. You allowlist the websites those URLs may come from; a URL from anywhere else is dropped before the card renders.

curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "config": {
      "components": {
        "image": {
          "web": {
            "enabled": true,
            "domains": ["photos.example.com", "*.cdn.example.com"],
            "guidance": "Show the listing photo whenever search_listings returns one."
          }
        }
      }
    }
  }'

Field	Type	Required	Description
`web.enabled`	boolean	❌	Defaults to `false`, unlike the component-level `enabled`. Setting `true` requires at least one entry in `domains`. Setting `false` keeps your saved list without deleting it.
`web.domains`	array	❌	The websites image URLs may come from, at most 20 entries.
`web.guidance`	string	❌	Your “when to show a web image” note, max 500 characters. Given to the PAL alongside the allowlist; never shown to the user.

Domain entries are validated when you save the config:

Each entry is an exact host (photos.example.com) or a leading wildcard (*.cdn.example.com). An exact host matches only itself. A wildcard matches any depth of subdomain and never the bare domain: *.example.com matches a.example.com and a.b.example.com but not example.com; list the apex separately if you want it too.
Hostname only, max 253 characters: no scheme, port, path, or userinfo. International domains go in as punycode (xn--...).
Entries are normalized on save (lowercased, trailing root dot stripped, duplicates removed), so the list you read back is the canonical form.
IP addresses (in any spelling), localhost, and internal-network names (.local, .internal, .corp, …) are rejected: the allowlist can only name public websites.
Wildcards over shared platforms and public suffixes (*.github.io, *.co.uk, …) are rejected, because they would allowlist every site anyone can register there. Wildcard your own subtree (*.photos.example.com) or list exact hosts instead.

The allowlist is for URLs the PAL receives during the conversation. It is instructed to pass only image URLs that appeared in a tool result, copied exactly, and never to construct or recall one from memory: an invented URL won’t load even on an allowed website. Pair web with a tool that returns image URLs.

If none of the curated documents resolve and web is not enabled, the canvas_show_image action is not compiled for that conversation at all. The PAL is never offered an image it cannot show.

When the PAL shows images

You can curate up to 50 Knowledge Base images on the PAL. Each canvas_show_image call can display 1 to 8 of them at once (and, with a live web allowlist, web image URLs as well). The PAL identifies each entry by curated id or by URL.

Multiple images on one card show as a carousel: one image at a time, with prev/next to step through them.

Arguments

Field	Type	Required	Description
`images`	array	✅	Images the PAL has chosen to show on this card, 1 to 8. More than 8 and the extras are dropped. One call may mix curated ids and web URLs.
`images[].id`	string	✅*	The `document_id` of a curated image. Ids outside the curated set are dropped.
`images[].url`	string	✅*	A web image URL, max 2048 characters. Only exists on PALs with a live `web` allowlist, and only renders if it passes URL validation.
`images[].caption`	string	❌	Caption for this image, max 280 characters. For a curated image it overrides your curated caption.
`images[].alt`	string	❌	Web URLs only, max 240 characters. Alt text for the image, which Tavus has never seen. Defaults to the caption.
`title`	string	❌	Heading above the card, max 120 characters.

* Each entry carries exactly one of id or url; an entry with both is dropped. No other arguments are accepted.

Example invocation

{
  "title": "Homes near the park",
  "images": [
    {
      "url": "https://photos.example.com/listings/1024.jpg",
      "alt": "Blue Victorian with a bay window",
      "caption": "312 Fell St"
    },
    { "id": "d1234567890" }
  ]
}

How an id becomes an image

At conversation create, Tavus resolves each curated document to a signed URL that is valid for the length of the conversation. When the PAL calls canvas_show_image, Tavus substitutes the id for that URL before the card reaches the browser, so the card your client renders (or your own renderer, if you bring one) receives a URL-shaped payload:

{
  "title": "Aurora Desk",
  "images": [
    {
      "url": "https://...",
      "alt": "A walnut standing desk photographed from the front left",
      "caption": "Aurora Desk in walnut"
    }
  ]
}

Caption precedence: the PAL’s caption, then your curated caption, then the description Tavus generated for the image (or the document name). Truncated to 280 characters.
Alt text for a curated image always comes from your config or Tavus, never from the PAL. Truncated to 240 characters.
title is truncated to 120 characters.
The resolved URLs are short-lived and specific to that conversation. Treat them as expiring; don’t store or share them.

How a URL becomes an image

A url entry is validated at the moment the PAL calls the action, in two layers:

A fixed safety floor. The URL must be https with a publicly routable hostname. Loopback, private-network, and link-local addresses, IP-literal hosts in any spelling, and internal names like localhost are rejected. The floor is not configurable: allowlisting a domain cannot re-admit an http:// or private-network URL.
Your allowlist. The URL’s host must match one of your web.domains entries, exact or wildcard.

A surviving URL reaches the renderer unchanged, in the same {url, alt, caption} shape as a curated image, with the PAL’s alt and caption. The participant’s browser fetches it directly, so the image must be publicly reachable. Whichever way an entry identifies its image, an entry that fails to resolve is dropped and the rest of the call still renders. If nothing survives, the card is not shown at all rather than rendering broken.

Interaction Types

image is lifecycle-only. Supported interaction types:

Type	What it means
`dismiss`	The user closed the card
`clear`	The canvas was cleared while the image was on screen
`error`	The client failed to display the image
`heartbeat`	A custom client’s periodic status ping

When to Use

Use image when seeing the thing is faster than describing it: a product, a floor plan, a chart you already have as a file, a screenshot of a step. Give each curated image a prompt that says when it applies, and the PAL will pick the right one. Use web when the right image isn’t known until mid-conversation: pair it with a tool that returns image URLs (a product search, an inventory lookup) and the PAL can show the participant what it just found. For walking a participant through a multi-page deck, use the presentation skill instead; it shares your screen with the deck rather than showing a card.

Canvas components overview: component table and shared behavior
Canvas configuration: the full magic_canvas skill config
Knowledge Base: uploading and managing documents

Getting started

Build

Deploy

Debug

Guides

Resources

Component: image

Configuration

Curated Knowledge Base images

Which documents can be curated

Web images

When the PAL shows images

Arguments

Example invocation

How an id becomes an image

How a URL becomes an image

Interaction Types

When to Use

​Configuration

​Curated Knowledge Base images

​Which documents can be curated

​Web images

​When the PAL shows images

​Arguments

​Example invocation

​How an id becomes an image

​How a URL becomes an image

​Interaction Types

​When to Use

​Related

Configuration

Curated Knowledge Base images

Which documents can be curated

Web images

When the PAL shows images

Arguments

Example invocation

How an id becomes an image

How a URL becomes an image

Interaction Types

When to Use

Related