English
Developer reference
ConvertAPI documentation
Convert web pages, HTML, and business documents into production-ready PDF or image files through a simple HTTP API.
API basics & authentication
Every conversion is a POST request. Send your API key as a body field named key; successful requests return JSON containing preview and download URLs.
BASE URL
https://convertapi.net/api
HTTPS recommended
Get an API key
- Sign in or create an account, then open the Applications page.
- Create an application. Its API key is generated automatically.
- Keep keys on your server—never expose them in browser code, public repositories, or logs.
- Use a separate application and key for each project so access can be rotated independently.
Request format
URL and HTML conversions accept regular form fields. File uploads must use multipart/form-data. The API always responds with JSON, including for errors.
Render a publicly reachable web page as a PDF. Use PDF options to control the rendering engine, paper, margins, JavaScript timing, headers, and footers.
POST
https://convertapi.net/api/pdf
form fields
| Method | POST | |||
|---|---|---|---|---|
| URL | https://convertapi.net/api/pdf | |||
| URL Params | - | |||
| DATA Params | "key" | String | Required | Your API Key. |
| "url" | String | Required | Page URL you want to convert to PDF. | |
| "options[]" | Array | Optional | Extra option for PDF file. | |
Quick example
curl --request POST "https://convertapi.net/api/pdf" \
--data-urlencode "key=YOUR_API_KEY" \
--data-urlencode "url=https://example.com/report" \
--data-urlencode "options[page-size]=a4" \
--data-urlencode "options[engine]=chromium"PDF options (optional)
| Option | Value | Description |
|---|---|---|
| options[engine] |
Omit or any value other than exact chromium → default wkhtmltopdf engine
chromium → Chromium/Puppeteer PDF engine (PDF endpoint only)
|
Optional PDF engine selector. Case-sensitive; only exact chromium selects the new engine.
Image endpoints ignore this option. Example URL request:
options[engine]=chromium. Example HTML request: same option with html body instead of url.
|
| options[page-size] |
a0 (841 × 1189 mm, 8.26 × 11.69 inches)
a1 (594 × 841 mm, 23.4 × 33.1 inches)
a2 (420 × 594 mm, 16.5 × 23.4 inches)
a3 (298 × 420 mm, 11.7 × 16.5 inches)
a4 (210 × 298 mm, 8.3 × 11.7 inches)
a5 (148 × 210 mm, 5.8 × 8.3 inches)
a6 (105 × 148 mm, 4.1 × 5.8 inches)
a7 (74 × 105 mm, 2.9 × 4.1 inches)
a8 52 × 74 mm, 2.0 × 2.9 inches)
a9 (37 × 52 mm, 1.5 × 2.0 inches)
b0 (1000 × 1414 mm, 39.4 × 55.7 inches)
b1 (707 × 1000 mm, 27.8 × 39.4 inches)
b2 (500 × 707 mm, 19.7 × 27.8 inches)
b3 (353 × 500 mm, 13.9 × 19.7 inches)
b4 (250 × 353 mm, 9.8 × 13.9 inches)
b5 (176 × 250 mm, 6.9 × 9.8 inches)
letter (216 × 279 mm, 8.5 × 11 inches)
legal (216 × 356 mm, 8.5 × 14 inches)
ledger (432 × 279 mm, 17 × 11 inches)
|
Define PDF page size Default "a4" |
| options[orientation] | portrait landscape |
Define PDF page orientation Default "portrait" |
| options[viewport-size] |
800x800 1366x800 1280x1024 |
Define Browser viewport size on converting. Default "800x800" |
| options[zoom] | From 0.1 to 2 | Page zoom on converting. Default "1" |
| options[margin-top] | In Millimeters (mm) | Set the page top margin. Default "10" |
| options[margin-bottom] | In Millimeters (mm) | Set the page bottom margin. Default "10" |
| options[margin-right] | In Millimeters (mm) | Set the page right margin. Default "10" |
| options[margin-left] | In Millimeters (mm) | Set the page left margin. Default "10" |
| options[javascript-delay] | In Milliseconds (ms) | Wait some milliseconds for javascript
finish. Default "200" |
| options[image-quality] | From 0 to 100 | When file contains jpeg images you can use this quality Default "94" |
| options[copies] | From 1 to 1000 | How many copies you want in the PDF file Default "1" |
|
options[disable-javascript]
options[enable-javascript]
|
1 | Empty option if you want to disable all javascripts. Default enable-javascript="" |
|
options[no-background]
options[background]
|
1 | Empty option if you want to hide file background. Backgrounds Enabled by Default background |
| options[grayscale] | 1 | Empty option if you want to convert as grayscale. |
PDF Header ( Optional )
| Option | Value | Description |
|---|---|---|
| options[header-html] |
|
Add a header for every page on PDF file. "Rendered HTML" |
| options[header-font-name] | Arial | Set header font name. default "Arial" |
| options[header-font-size] | 12 | Set header font size. default "12" |
|
options[header-center]
options[header-left]
options[header-right]
|
1 | Define align for header text |
|
options[header-line]
options[no-header-line]
|
1 | Display line below the header. default "no-header-line" |
|
options[header-spacing]
|
In Millimeters (mm) | Spacing between header and content in mm. default "0" |
| Option | Value | Description |
|---|---|---|
| options[footer-html] |
|
Add a footer for every page on PDF file. "Rendered HTML" |
| options[footer-font-name] | Arial | Set footer font name. default "Arial" |
| options[footer-font-size] | 12 | Set footer font size. default "12" |
|
options[footer-center]
options[footer-left]
options[footer-right]
|
1 | Define align for footer text |
|
options[footer-line]
options[no-footer-line]
|
1 | Display line below the footer. default "no-footer-line" |
|
options[footer-spacing]
|
In Millimeters (mm) | Spacing between footer and content in mm. default "0" |
Capture a publicly reachable web page as PNG or JPEG. Select the output format in the endpoint path and use image options to control the viewport and page timing.
POST
https://convertapi.net/api/{png|jpg|jpeg}
form fields
| Method | POST | |||
|---|---|---|---|---|
| URL |
https://convertapi.net/api/png
https://convertapi.net/api/jpg
https://convertapi.net/api/jpeg
|
|||
| URL Params | - | |||
| DATA Params | "key" | String | Required | Your API Key. |
| "url" | String | Required | Public page URL you want to capture as an image. | |
| "options[]" | Array | Optional | Rendering options for the output image. | |
Quick example
curl --request POST "https://convertapi.net/api/png" \
--data-urlencode "key=YOUR_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "options[width]=1366" \
--data-urlencode "options[height]=800"Image options (optional)
| Option | Value | Description |
|---|---|---|
| options[width] | Integer | Define image width in pixel. Default "800" |
| options[height] | Integer | Define image height in pixel. Default "800" |
| options[zoom] | From 0.1 to 2 | Page zoom on converting. Default "1" |
| options[javascript-delay] | In Milliseconds (ms) | Wait some milliseconds for javascript
finish. Default "200" |
|
options[disable-javascript]
options[enable-javascript]
|
1 | Empty option if you want to disable all javascripts. Default enable-javascript="" |
Upload a Microsoft Office, OpenDocument, or plain-text file and convert it to PDF. The conversion preserves the source document's page layout and does not use the URL/HTML PDF options documented above.
POST
https://convertapi.net/api/document-to-pdf
multipart/form-data
Request fields
| Field | Type | Requirement | Description |
|---|---|---|---|
key |
String | Required | An active application API key with an active subscription and available conversion quota. |
file |
Binary file | Required | One supported document, up to 25 MiB. |
cURL example
curl --request POST "https://convertapi.net/api/document-to-pdf" \
--form "key=YOUR_API_KEY" \
--form "file=@/path/to/report.docx"
Send the original binary file
Use a multipart file upload. Do not base64-encode the document, wrap it in JSON, or send a remote file URL. The options field is not supported by this endpoint.
Supported document formats
Text documents
doc docx odt rtf txt dot dotx ott
Spreadsheets
xls xlsx ods csv tsv xlt xltx ots
Presentations
ppt pptx odp pps ppsx pot potx otp
Drawings
odg
File validation and fidelity
The file extension, MIME type, and internal document structure must agree. Macro-enabled, password-protected, corrupt, PDF, HTML/XML, archive, and executable files are rejected. txt, csv, and tsv files must be valid NUL-free UTF-8. Font substitution can affect layout when a source font is unavailable on the conversion server.
Conversion behavior
- Page size, orientation, margins, headers, footers, and print areas come from the uploaded document.
- The request completes after conversion and returns links to the stored PDF; it does not stream PDF bytes directly.
- A conversion is deducted from your subscription quota only after the PDF is generated and saved successfully.
- The generated PDF is limited to 50 MiB.
- Requests are limited to 5 document conversions per minute per IP address.
Success response
{
"status": "success",
"msg": "success",
"preview": "https://convertapi.net/...",
"download": "https://convertapi.net/..."
}| Field | Type | Description |
|---|---|---|
status | String | success when the PDF was generated and stored. |
msg | String | Human-readable result message. |
preview | URL | Opens the generated PDF in the file preview. |
download | URL | Downloads the generated PDF. |
Error responses
All failures return JSON with status: "error", a string code, and a safe msg. Use the HTTP status for transport behavior and the API code for application logic.
| HTTP | Code | Message / meaning | Recommended action |
|---|---|---|---|
| 500 | -1 | Invalid or missing API key, invalid application/customer, or unexpected failure. | Verify credentials and application status; contact support if the request is otherwise valid. |
| 500 | -2 | Account is not active. | Contact administration. |
| 500 | -3 | No active subscription. | Activate or renew a subscription. |
| 500 | -4 | Allowed file quota exceeded. | Upgrade or renew the subscription quota. |
| 422 | -6 | File is required or the upload is invalid. | Send one non-empty file in the file field. |
| 415 | -7 | Unsupported document type. | Use a listed format and preserve the correct filename extension. |
| 413 | -8 | Uploaded document is too large. | Reduce the source file below the published input limit. |
| 422 | -9 | Document is corrupt, password protected, or cannot be converted. | Repair, decrypt, or re-export the source document. |
| 503 | -10 | Document conversion service unavailable. | Retry later; contact support if it persists. |
| 504 | -11 | Conversion timed out. | Retry once or simplify the source document. |
| 500 | -12 | Conversion failed or produced invalid output. | Retry once; re-export the source if it repeats. |
| 422 | -13 | Generated PDF exceeds the output limit. | Reduce images, pages, or embedded content. |
| 503 | -14 | Conversion service is busy. | Retry with exponential backoff. |
| 429 | -15 | Too many document conversions. | Wait for the rate-limit window and retry with backoff. |
Render an HTML string directly to PDF. This is useful when your application already produces complete HTML and does not need the API to fetch a public URL.
POST
https://convertapi.net/api/pdf
form fields
| Method | POST | |||
|---|---|---|---|---|
| URL | https://convertapi.net/api/pdf | |||
| URL Params | - | |||
| DATA Params | "key" | String | Required | Your API Key. |
| "html" | String | Required | Rendered HTML you want to convert to PDF. | |
| "options[]" | Array | Optional | Extra option for PDF file.
All Options of PDF available. |
|
Quick example
curl --request POST "https://convertapi.net/api/pdf" \
--data-urlencode "key=YOUR_API_KEY" \
--data-urlencode "html=<!doctype html><html><body><h1>Invoice</h1></body></html>" \
--data-urlencode "options[page-size]=a4"