> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# File conversions

> Convert document formats or reconstruct editable content from PDFs and images.

[`POST /v1/convert`](/developer/docs/developer/docs/revise-api/reference/create-conversion) 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](/developer/docs/developer/docs/revise-api/models).

## Submit and retrieve

```bash theme={null}
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.

```ts theme={null}
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](/developer/docs/developer/docs/revise-api/pricing).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.