List images in a PDF

Provide the image descriptors for each page, including the page number and every image's pixel dimensions. The result is one flat list in source order, with a one-based index added for each image on its page. This is useful after a PDF parser has identified embedded images but before another system needs to audit, select, export, or report on them.

Prepare per-page image descriptors

Start with the metadata produced by your PDF reader or extraction pipeline. The input is a pages array, and every page entry contains a positive page number plus an images array. Each image needs a positive integer width and height in pixels. Keep images in the order reported by the parser because that order becomes the image index in the result. The index starts at one for every page, which makes it convenient for people to read and for reports to describe an item such as “page 4, image 2.” Pages may contain no images; include an empty images array when retaining that page is helpful to your workflow. Page numbers do not need to be consecutive, so metadata for selected pages can be processed without adding placeholders. They must, however, be unique within a request. This explicit structure prevents a missing page label from silently attaching an image to the wrong location and keeps the inventory tied to the PDF metadata that produced it.

Understand the flattened result

The response contains an images array with one record for every descriptor found across all supplied pages. Each record has exactly four useful fields: page, index, width, and height. Page is copied from the containing page entry. Index is calculated from the image's position within that page and restarts at one on the next page. Width and height are copied after validation, without resizing, rounding, rotation, or unit conversion. Records preserve the order of the page entries you submit and the order of images inside each entry. That stable traversal makes repeated runs deterministic and lets a downstream job compare inventories without an unexpected sort step. The capability does not open a PDF or extract binary image data; it normalizes descriptors already obtained from a PDF parser. As a result, duplicated dimensions remain separate records, because two images with the same size can still be distinct PDF resources or placements. Empty page image arrays simply contribute no records to the flat list.

Validate and use the inventory

Use the flat inventory wherever nested page metadata is inconvenient. A quality check can flag images below a minimum resolution, an extraction job can choose only records larger than a thumbnail, and an audit report can count images by page without repeatedly walking nested arrays. Store page and index together as the human-readable location of an image, while remembering that the index describes the supplied order rather than an internal PDF object identifier. Validation is deliberately strict. The request fails when pages is missing or empty, when page numbers are duplicated or invalid, when an images value is not an array, or when a width or height is not a positive integer. A failure is preferable to producing a partial inventory that looks complete. The operation is deterministic, uses no network access, and does not retain descriptors. You can run it in the browser for interactive work or call the API for $0.002 per request when the inventory belongs in an automated PDF processing pipeline.