Inline pictures

The API edits inline PNG and JPEG pictures. Use Body.inlinePictures or Range.inlinePictures to discover pictures. Floating shapes, picture bullets, and a general Shape object are outside this subset.

Create a runtime with Runtime and setup. Use context and document proxies inside runtime.run().

Insert image bytes

Range.insertInlinePictureFromBase64(base64EncodedImage, location) accepts Replace, Start, End, Before, or After. Pass the base64 image bytes, and sync before configuring the returned InlinePicture.

This server example reads a PNG file and inserts it after the first paragraph's content:

import { readFile } from 'node:fs/promises';

const imageBase64 = (await readFile('logo.png')).toString('base64');
await runtime.run(async (context) => {
  const paragraph = context.document.paragraphs.getFirst();
  paragraph.load('text');
  await context.sync();
  const anchor = paragraph.getRange('End');
  await context.sync();
  const picture = anchor.insertInlinePictureFromBase64(imageBase64, 'After');
  await context.sync();
  picture.altTextDescription = 'Company logo';
  picture.lockAspectRatio = true;
  picture.width = 96;
  await context.sync();
});

The runtime validates the image format and bytes. The runtime rejects unsupported formats and invalid image bytes. The API adds package media resources through its document transaction.

Read picture properties

Load the collection, then load individual properties:

const descriptions = await runtime.run(async (context) => {
  const pictures = context.document.body.inlinePictures;
  pictures.load('items');
  await context.sync();
  for (const picture of pictures.items) {
    picture.load(['width', 'height', 'altTextDescription']);
  }
  await context.sync();
  return pictures.items.map((picture) => ({
    width: picture.width,
    height: picture.height,
    description: picture.altTextDescription,
  }));
});

InlinePictureCollection exposes items, getFirst(), getLast(), getFirstOrNullObject(), and getLastOrNullObject(). Check isNullObject after sync when using a nullable accessor. A range collection includes pictures fully contained within that range.

Resize and describe a picture

When aspect locking applies, changing one dimension preserves the ratio. If aspect ratio is locked, the runtime rejects conflicting width and height assignments. Batch compatible settings on the same picture proxy. Use a description that conveys the image's purpose to a reader.

Handle errors

Newly inserted pictures need sync before resizing, loading, or deleting them. Edits can fail if the target is protected, unsupported, or contains pending revisions. The runtime's tracking mode does not support image insertion, removal, or formatting. A failed write batch applies none of its document changes. Earlier successful syncs remain committed.

For another picture variant, prepare supported PNG or JPEG bytes before insertion. This API does not expose cropping, rotation, replacement-by-URL, or floating-picture positioning methods.

Next steps

See Text and ranges, Batching, loading, and errors, and API member directory.