Convert Document
convert_documentConverts documents between 100+ formats (Office, PDF, images, HTML) while preserving Carbone template tags. Supports PDF options like watermarks, passwords, or page ranges.
Instructions
Convert any document to another format without storing a template. Supports 100+ input/output format combinations: Office documents, PDFs, images, web pages, spreadsheets, and more. The source file can be a local path, a URL, or a base64 string. Carbone tags are PRESERVED, not resolved: converting a template keeps every {d.field} intact, so this is also how you proof a template in another format (DOCX template → PDF, or DOCX → ODT while it stays a template). Use render_document instead when you need data injection ({d.field} tags resolved), translations, or batch generation. Common conversions: DOCX → PDF (file: "report.docx", convertTo: "pdf"; add converter: "I" for the fastest DOCX→PDF path), XLSX → PDF (file: "data.xlsx", convertTo: "pdf"), PPTX → PDF (file: "slides.pptx", convertTo: "pdf", converter: "O" for best fidelity), HTML → PDF (file: "page.html", convertTo: "pdf", converter: "C" for full CSS/JS rendering), DOCX → HTML (file: "doc.docx", convertTo: "html"), XLSX → CSV (file: "sheet.xlsx", convertTo: "csv"), PDF → PNG (file: "doc.pdf", convertTo: "png"), PPTX → PNG (first slide as image), MD → PDF (file: "readme.md", convertTo: "pdf").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. "/home/user/report.docx" or "./invoice.xlsx". (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown (MD), TXT, CSV, RTF, PDF, PNG and JPG. Carbone reads XML-based and text-based documents only, so the legacy BINARY Office formats DOC, XLS and PPT are REJECTED as input — Carbone can produce them as output but cannot read them. Re-save such a file as DOCX/XLSX/PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md | |
| convertTo | Yes | Target output format. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub", plus the legacy "doc", "xls", "ppt" (output only — Carbone writes them but cannot read them back). Web/text : "html", "xhtml", "txt", "csv", "md", "xml", "idml". Images : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". Archive : "zip" (batch output). Simple usage: "pdf". Advanced usage: { "formatName": "pdf", "formatOptions": { "EncryptFile": true, "DocumentOpenPassword": "secret" } }. | |
| converter | No | Converter engine. Only relevant when convertTo is "pdf" (or an image format rasterised from a document). "L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. "O" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). "C" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. "I" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick "I" when the request needs a password or restricted permissions; use "L" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default. | |
| outputPath | No | Optional local file path to save the converted document to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. | |
| reportName | No | Filename (WITHOUT extension) for the converted document, returned in the Content-Disposition header. Carbone appends the extension matching convertTo, so do not include one — "report.pdf" yields "report.pdf.pdf". Examples: "contract", "2026-invoice". Unlike render_document, Carbone tags are NOT resolved here (conversion does not run templating), so pass a literal name rather than a pattern like "{d.id}" — a pattern would come back verbatim. Ignored when returnLink is set, which returns a download URL rather than a named file. | |
| returnLink | No | If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment. | |
| hardRefresh | No | Forces Carbone to run the converter even when the output format already matches the input format. Only useful for PDF: converting PDF → PDF to APPLY formatOptions (watermark, password, PDF/A, page range). Without it Carbone may pass the file straight through and none of those options take effect. Leave unset for any format-changing conversion (DOCX → PDF, XLSX → CSV, …), where the converter runs anyway. | |
| asAttachment | No | If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set. | |
| egressAuthorization | No | Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example "Bearer abc123" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 512 characters. |