Function imageToBuffer

Converts an image input from any of the supported formats into a Buffer.

Supported input formats:

• Buffer — returned as-is.
• Data URL (RFC 2397) — data:image/png;base64,iVBOR... is decoded from base64; one without ;base64, such as data:image/svg+xml,%3Csvg%3E..., is percent-decoded byte by byte.
• Raw base64 string — decoded. A string that does not look like a URL or a file path is decoded directly. One that looks like a path is read as a file first, and decoded when no file exists there and it is base64 (standard or URL-safe) whose bytes start with a PNG, JPEG, GIF, WebP, TIFF, AVIF, HEIC, BMP, ICO, JPEG 2000, JPEG XL or SVG signature: standard base64 uses / (RFC 4648, Table 1), so a JPEG's base64 begins with /9j/. A missing path is still an error; when the string is base64 of another format, the error says so without repeating the string.
• file: URL — converted to a local path with fileURLToPath and read.
• HTTP/HTTPS URL — fetched via globalThis.fetch and buffered.
• Local file path — a string that contains / or \, or ends in a file extension, is read with fs.readFile.

A string from an untrusted source can name any file the process can read, and a URL can point at this machine or a private network, a cloud metadata service among them. Pass { untrusted: true } for such input: file paths and file: URLs are refused (raw base64 of a recognised image format is still decoded), and an http(s) URL is fetched only from public network addresses, checked at every connection and every redirect, within maxBytes and timeoutMs. An image decoded from the string is refused when it is larger than maxBytes.

@param input - The image in any supported format. @param options - {@link ImageToBufferOptions}; untrusted for input from a model or a user. @returns A Buffer containing the raw image bytes.

@throws {TypeError} When input is neither a string nor a Buffer. @throws {RangeError} With untrusted, when maxBytes is not a positive number. @throws {Error} When a remote URL fetch fails or the file cannot be read; with untrusted, also when the input names a local file (code: 'IMAGE_LOCAL_FILE_REFUSED'), a URL whose address or redirect is refused (code: 'IMAGE_URL_REFUSED'), or an image larger than maxBytes.

Example

const buf1 = await imageToBuffer('data:image/png;base64,iVBOR...');
const buf2 = await imageToBuffer(fs.readFileSync('photo.png'));
const buf3 = await imageToBuffer('https://example.com/photo.png');
const buf4 = await imageToBuffer('/absolute/path/to/image.jpg');
// A URL a model's tool call gave: public hosts only, 50 MiB and 30 s at most.
const buf5 = await imageToBuffer(toolArgs.imageUrl, { untrusted: true });
Copy