Images

Your AI assistant uses these tools to find photos on Pixabay or Wikimedia Commons, with their licence and credit, and to add images to your slides from any public URL. Just describe what image you want and where — the assistant handles searching, fetching, uploading, and positioning.

Photos are found with image_search, which returns candidates with their thumbnails, licence and credit. Images are added with element_create_image, which fetches an image from a URL, uploads it to Rideful's storage, and places it on your slide as an element. The image is stored permanently — the original URL doesn't need to stay accessible after upload.

For other element types (shapes, text, lines), see Element Operations. To update an existing image's crop, mask or alt text after it's been added, use element_bulk_update (documented on the Element Operations page).

Finding a Photo

When you ask for “a portrait of Max Wertheimer” or “a photo of a team at a whiteboard,” your assistant usesimage_searchto find existing photos. Each candidate comes back as a line of JSON followed by its thumbnail as image content, so the assistant chooses by eye. It is read-only and free.

Parameters

Each Candidate

• index — 1-based, stable within the result
• url — the file sized for a slide: up to 1280 px on the long edge from Pixabay, 1920 or 1280 px wide from Commons. Pass it toelement_create_image as sourceUrl
• width — and height: that file's size in pixels
• lowRes — under 800 px on the long edge; it turns soft in a box larger than the file, so size the box to it
• description — a stock photo's tags, or a Commons file's description
• creditLine — “Image by Jane Doe from Pixabay”, or “John Doe / CC BY-SA 4.0”, beside author andlicence
• attributionRequired — true for CC BY and CC BY-SA files
• sourcePage — the photo's page on Pixabay or Commons
• restrictions — when present, such as personality ortrademarked: the file shows a real person or a brand

structuredContentcarries the same candidates without the thumbnails.

Tips

• A named subject queried by its Wikipedia title (“Max Wertheimer”, “Eiffel Tower”) returns that article's lead image alone; added words (“Eiffel Tower at night”) search Commons' files instead
• Commons returns only public-domain, CC0, CC BY and CC BY-SA files. Pixabay photos need no attribution
• Never place a different picture as a named person or place when nothing fits; say so instead
• Put the creditLine at the end of altText, and whenattributionRequired is true, also place it as a small caption beside the picture
• A found face or logo never stands beside a product claim as if that person or brand endorsed it
• No match is a success with no candidates and a line suggesting what to try. A provider that is down or rate-limited is an error naming the source
• Results are cached for 24 hours, so a repeated search is instant

// Find a photo, then fill the left half of a 1280×720 slide with it
image_search({
  query: "team whiteboard",
  source: "stock",
  orientation: "portrait"
})

element_create_image({
  deckId: "deck_abc123",
  slideId: "slide_002",
  sourceUrl: "<candidate url>",
  x: 0, y: 0,
  width: 640, height: 720,
  fit: "cover",
  altText: "A team planning at a whiteboard. Image by Jane Doe from Pixabay"
})

Adding an Image to a Slide

When you ask to “add a photo of the team” or “put the revenue chart on slide 3,” your assistant uses element_create_image to fetch the image and place it on the slide: a link you gave, or a candidate from image_search. The image is fetched server-side, so CORS restrictions don't apply.

Parameters

Sizing & Aspect Ratio

How your assistant sizes images depends on what you specify:

• Set only width — height is calculated automatically to preserve the original aspect ratio
• Set only height — width is calculated automatically to preserve the original aspect ratio
• Set both — the whole image fits inside that box, preserving its aspect ratio
• Set both with fit: "cover" — the image fills the box exactly, cropped about its centre, such as a full-bleed photo or one half of a split slide. The crop is stored on the element, so the editor's Reset crop shows the whole picture
• Omit both — the image is automatically sized to fit within the slide

The response always includes the original image dimensions (imageWidth, imageHeight) so the assistant can make informed layout decisions.

What It Returns

• elementId — the image element's ID (use for updates or deletion)
• position — { x, y } final position in pixels
• size — { width, height } final display size in pixels
• imageWidth, imageHeight — original image dimensions
• imageMimeType — detected format (e.g., image/png)
• zIndex — layer order on the slide

Examples

Add an Image with Width

Setting only width preserves the aspect ratio — height is calculated automatically.

element_create_image({
  deckId: "deck_abc123",
  slideId: "slide_002",
  sourceUrl: "https://example.com/charts/revenue-q4.png",
  x: 640, y: 160,
  width: 560,
  altText: "Q4 revenue chart showing 18% growth"
})

// Response:
// {
//   elementId: "elem_img001",
//   type: "image",
//   slideId: "slide_002",
//   position: { x: 640, y: 160 },
//   size: { width: 560, height: 420 },
//   imageWidth: 1600,
//   imageHeight: 1200,
//   imageMimeType: "image/png",
//   zIndex: 3
// }

Auto-Center and Auto-Fit

Omit position and size to let Rideful center the image and fit it within the slide.

// Omit x, y, width, and height to auto-center and auto-fit
element_create_image({
  deckId: "deck_abc123",
  slideId: "slide_003",
  sourceUrl: "https://example.com/photos/team.jpg"
})

// The image is centered on the slide and sized to fit

Crop an Image

Use crop to trim edges of the image by percentage. This is useful for removing unwanted borders or focusing on a specific area.

// Crop 10% from the top and 15% from the right
element_create_image({
  deckId: "deck_abc123",
  slideId: "slide_004",
  sourceUrl: "https://example.com/photos/office.jpg",
  x: 0, y: 0,
  width: 640, height: 720,
  crop: {
    top: 10,
    right: 15,
    left: 0,
    bottom: 0
  },
  altText: "Office panoramic view"
})

Updating Images After Adding

Once an image is on a slide, your assistant can modify its position, size, crop, and alt text using element_bulk_update. To replace an image entirely, delete the existing one and add a new one.

Updatable Image Properties

Example

// Update an existing image's crop, mask and alt text
// (use element_bulk_update; mask: null removes a mask)
element_bulk_update({
  deckId: "deck_abc123",
  updates: [
    {
      elementId: "elem_img001",
      altText: "Updated Q4 revenue chart",
      crop: { left: 5, top: 0, right: 5, bottom: 10 },
      mask: { shapeType: "rectangle", cornerRadius: 24 }
    }
  ]
})

Requirements & Limits

• HTTPS only — HTTP URLs are not supported
• Supported formats — PNG, JPEG, GIF, WebP
• No SVG — SVG images are not supported
• Maximum file size — 10MB
• Redirects — up to 3 redirects are followed, but all must use HTTPS
• Crop limits — left + right and top + bottom must each be ≤ 95% (at least 5% of the image must remain visible)

Related

• Element Operations — Create and style shapes, text, and lines; update or delete any element including images
• How Do I Add Images to Slides? — Step-by-step guide with tips on image sizing and placement
• Slide Operations — Inspect slide contents to see existing images and elements
• Canvas Size — Slide dimensions and the coordinate system for positioning