Embed image in PDF
embed_imageIdempotent
Create a PDF with one JPEG, PNG, or JPEG 2000 image from base64 data, plus optional caption, render dimensions, PDF/A, print, metadata, and encryption settings.
Instructions
PDF with one embedded JPEG, PNG or JPEG 2000 image (base64; PNG without alpha channel; JPEG 2000 passed through as /JPXDecode) plus optional caption and render width/height. Inside a longer document use an 'image' block of generate_basic_pdf instead. PDF/A, print, metadata and creationDate options as on every document tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Accessible description of the image (tagged /Figure /Alt). Provide it for non-decorative images under PDF/A or PDF/UA. | |
| pdfA | No | PDF/A level: pdfa1b (simple text+images), pdfa2b/pdfa2u (richer; 2u = Unicode mapping), pdfa3b (attachments / Factur-X). Pair with embedFonts=true for a valid claim. Exclusive with encryption. See docs/guides/PDFA.md. | |
| pdfx | No | PDF/X-4 print exchange (ISO 15930-7). REQUIRES outputIntent with the printer's ICC profile (device class 'prtr'; CMYK or Gray — none is bundled); needs embedFonts:true for a conformant file (PDFX_NO_FONT_ENTRIES otherwise, strict:true refuses). Combines with pdfA:'pdfa2b' | 'pdfa2u' (dual claim) but not pdfa1b / pdfa3b; exclusive with encrypt; metadata.trapped must be 'True' or 'False'; TrimBox or ArtBox, not both. Links and form fields are reported (PDFX_ANNOTATIONS). Check with validate_pdf standard:'pdf-x-4'. See the print_ready prompt. | |
| align | No | Horizontal placement of the image inside the content width. | left |
| debug | No | Draw margin / block / cell guide rectangles (unmarked content — not for PDF/UA output). Geometry unchanged. Default false. | |
| No | Print production (ISO 32000-1 §14.11): page boxes, `bleed` shorthand (TrimBox = MediaBox inset), crop/registration marks outside the TrimBox, /UserUnit for large formats (PDF 1.7; not under pdfa1b), `spotColours` ink declarations. See docs/guides/PRINT.md. | ||
| title | Yes | Document title rendered at the top and used as PDF metadata title. | |
| width | No | Render width in points. If omitted, the image is auto-sized to fit the page. | |
| height | No | Render height in points. If omitted, aspect ratio is preserved. | |
| strict | No | Fail instead of producing a file the engine warns about: a PDFA_* diagnostic → PDF_A_COMPLIANCE_VIOLATION (e.g. PDFA_NO_FONT_ENTRIES without embedFonts), a PDFX_* one → PDF_X_COMPLIANCE_VIOLATION, any other (TYPOGRAPHY_FEATURE_INEFFECTIVE, TEXT_GLYPH_NOT_COVERED — a character no font covers, drawn as a box or '?') → DIAGNOSTIC_ESCALATED. Pair with embedFonts=true. | |
| caption | No | Optional caption rendered below the image. | |
| encrypt | No | Encrypt at build time (AES-128 default / AES-256) and KEEP the AcroForm — unlike encrypt_pdf, which rebuilds the page tree. Exclusive with pdfA. Randomised output, never cached. | |
| margins | No | Margins in points, all four required (0–200). Default 45 / 36 / 35 / 36. | |
| compress | No | FlateDecode the streams (smaller file, different bytes; PDF/A unaffected, XMP stays plain). Default false. | |
| metadata | No | /Info (+ XMP under PDF/A): author, subject, keywords, /Trapped. | |
| mimeType | Yes | MIME type of the image. Must match the actual encoding of imageBase64 (magic bytes are checked). 'image/jp2' accepts a JP2 file (.jp2/.jpx) or a raw JPEG 2000 codestream (.j2k/.j2c). | |
| pageSize | No | Portrait page preset (points): A4 595.28×841.89 (default), Letter 612×792, Legal 612×1008, A3 841.89×1190.55, Tabloid 792×1224. print.* boxes must fit it. | |
| direction | No | Base text direction (UAX #9): 'auto' reads each paragraph's first strong character and right-aligns RTL ones; 'ltr' / 'rtl' force it. A paragraph's own direction overrides it. Omitted = LTR (1.7.0 bytes). | |
| actualText | No | Untagged output: wrap reordered shaped runs and RTL runs in /ActualText so extract_text returns reading order. Default true; false = bare 1.7.0 glyph runs. No effect on tagged (pdfA) output. | |
| embedFonts | No | Embed Noto Sans Latin instead of the viewer base-14 Helvetica. REQUIRED for a valid PDF/A or PDF/X claim (every font embedded) and for strict=true; adds ~0.3 MiB. | |
| outputMode | No | Either 'base64' (returns the PDF inline) or 'file' (writes to a sandboxed path inside PDFNATIVE_MCP_OUTPUT_DIR). | base64 |
| outputPath | No | Required when outputMode='file'. Relative path inside the sandbox; must end with .pdf. | |
| typography | No | Fine typography, all opt-in (omitted = unchanged bytes). kerning and fontFeatures need embedFonts:true ('fr' works on base-14 too). No hyphenation dictionary is installed: use soft hyphens (U+00AD). See the typography prompt. | |
| imageBase64 | Yes | Base64 image bytes. JPEG (baseline; 1, 3 or 4 components — CMYK raises PDFA_DEVICE_CMYK_IMAGE under PDF/A), PNG (8-bit greyscale/RGB, non-interlaced; alpha-channel and palette PNGs are rejected with a remedy) or JPEG 2000 (JP2 file or raw .j2k codestream, passed through as /JPXDecode; PDF 1.5+, so PDFA1_JPX_IMAGE under pdfa1b). No data: URI. | |
| creationDate | No | ISO-8601 instant for /CreationDate (+ XMP, the trailer /ID and the {date} placeholder), written in UTC. Pin it for byte-identical output across calls and hosts; omitted = wall clock, so every call differs. | |
| outputIntent | No | Custom OutputIntent (under pdfA or pdfx): an RGB, CMYK or Gray ICC profile + condition strings, replacing the built-in sRGB intent. The profile must be a real ICC file ('acsp' signature, consistent size — PRINT_ERROR otherwise); pdfx needs device class 'prtr'. Under a CMYK / Gray intent RGB content is mapped through a calibrated default space. | |
| footerTemplate | No | Running footer on every page. Replaces the default footer: footerText is then ignored and page numbers appear only via {page}/{pages}. | |
| headerTemplate | No | Running header on every page (left / center / right zones); reserves 15 pt. | |
| includeDiagnostics | No | Return the diagnostics raised while building (PDFA_*, PDFX_*, TYPOGRAPHY_*, TEXT_GLYPH_NOT_COVERED) as `diagnostics[]` (possibly empty). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded. | |
| mode | Yes | ||
| summary | No | Tool-specific summary, when produced. | |
| filePath | No | Sandboxed absolute path (file mode). | |
| sizeBytes | Yes | ||
| diagnostics | No | Engine diagnostics (when includeDiagnostics=true). |