File conversions

POST /v1/convert accepts an uploaded file_id and an output format. It returns a conversion receipt to poll. Conversion inputs cannot be artifact IDs; the TypeScript helper downloads and reuploads previous results automatically.

Supported formats

Input	Processing	Output
DOCX, Markdown, HTML, plain text, RTF, ODT	Deterministic format conversion	`docx`, `pdf`, `md`, `html`, `txt`
PDF	AI reconstruction from page images	`docx`, `md`, `html`, `txt`
JPEG, PNG, WebP, GIF	AI reconstruction from an image	`docx`, `pdf`, `md`, `html`, `txt`

Same-format conversion is rejected, including PDF to PDF. .markdown and .htm are recognized aliases. Text, Markdown, and HTML uploads must be UTF-8. RTF, ODT, and image formats are input-only. Deterministic conversion uses the document’s structure and supported formatting. PDF and image scanning reconstructs headings, paragraphs, lists, and tables. It does not reproduce the page pixel for pixel. Each image is one scanned page. Scanning requires OpenAI. Managed scans use the default OpenAI model. With your own OpenAI key, you can choose another catalogued OpenAI model. Deterministic conversions reject nonempty inference settings. See models and provider keys.

Submit and retrieve

curl --fail-with-body 'https://revise.io/api/v1/convert' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: export-42' \
  -d '{"input":{"file_id":"file_REPLACE_ME"},"output":{"format":"pdf"}}'

Poll until succeeded, failed, or cancelled. On success, download output.artifact. Its variant is converted. The receipt’s mode is deterministic or vision; usage.conversion records the billed unit, quantity, and rate.

import { ReviseClient, Source } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const edited = await revise.edit(
  Source.fromPath("contract.docx"),
  "Change the payment term to 30 days.",
  { idempotencyKey: "contract-42-edit" },
);
const pdf = await revise.convert(edited, "pdf", {
  idempotencyKey: "contract-42-pdf",
});
await pdf.save("contract.pdf");

Use revise.conversions.create(body) to submit without waiting, or revise.conversions.run(body) to wait for success when you already have a file ID. Download/reupload steps are subject to the 18 MiB input limit, even when a previous output was larger.

Pricing and limits

Deterministic conversions cost $0.005 each**. Scans cost **$ 0.02 per page, including managed inference, or $0.005 per page plus your provider’s inference charge when using your own OpenAI key. Conversions have no separate CPU charge and do not count toward prompt request-fee tiers. See pricing and usage. Uploads are limited to 18 MiB, PDFs to 100 pages, and conversion output to 50 MiB before encryption. JWE encoding increases downloaded size. There is no default spending cap. If you set max_platform_cost_usd, a scan that exceeds it fails with conversion_limit_exceeded before inference. PDF structure is checked at upload and again during processing. A failed job can report:

Code	Action
`pdf_page_limit_exceeded`	Split the PDF into files of at most 100 pages.
`pdf_password_protected`	Remove the password before uploading.
`invalid_pdf`	Export a valid PDF and retry.
`empty_pdf`	Supply a PDF with at least one page.
`conversion_output_too_large`	Split or simplify the input to reduce output size.

These validation failures are not billed by Revise. Cancellation after processing starts can be billed; inspect settled usage rather than inferring cost from status alone. After retention expiry or deletion, the receipt remains but the artifact is unavailable and some format fields may be empty.

Getting started

Guides

REST reference

Supported formats

Submit and retrieve

Pricing and limits

​Supported formats

​Submit and retrieve

​Pricing and limits

Supported formats

Submit and retrieve

Pricing and limits