Guide
Print-ready PDF/X
Turn a PDF into a PDF/X-1a, X-3 or X-4 file for your printer: colour profile, bleed and the Gelato preset.
The convert-pdfx operation turns a PDF into a print-ready PDF/X file: it identifies the file as PDF/X-1a, PDF/X-3 or PDF/X-4, converts every colour to CMYK for the printing condition you choose, embeds every font and, if you ask for it, adds bleed around every page. Send the result straight to a print shop or a print-on-demand service such as Gelato.
The input must be a PDF. To print a Word document or an image, convert it to PDF first.
Basic request
Create a job with the operation category and the convert-pdfx target. This example asks for PDF/X-4 for coated paper in Europe, with 3 mm of bleed:
curl -X POST "https://api.api2convert.com/v2/jobs" \
-H "x-api2convert-api-key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"type": "remote",
"source": "https://example-files.online-convert.com/document/pdf/example.pdf"
}
],
"conversion": [
{
"category": "operation",
"target": "convert-pdfx",
"options": {
"pdfx_standard": "pdfx4",
"color_profile": "fogra39",
"bleed_mm": 3
}
}
]
}'Every option is optional: without any, you get PDF/X-4 for Coated GRACoL 2006 and no bleed. Poll the job until it is completed and download the file from its output, as shown in the Quickstart.
Options
| Option | Type | Values | Default |
|---|---|---|---|
pdfx_standard |
string | pdfx1a (PDF/X-1a:2001), pdfx3 (PDF/X-3:2002), pdfx4 (PDF/X-4) |
pdfx4, or the standard of printer_preset |
color_profile |
string | gracol2006 (Coated GRACoL 2006), fogra39 (Coated FOGRA39) |
gracol2006, or the profile of printer_preset |
bleed_mm |
number | 0 to 20 millimetres, decimals allowed |
0, or the bleed of printer_preset |
printer_preset |
string | gelato |
none |
A value outside these is refused when the job is created, with 400 Invalid input, before anything is converted.
Choose a PDF/X standard
Ask your printer which standard they expect. If they do not mind, keep the default, PDF/X-4.
pdfx_standard |
Standard | Transparency | PDF version of the output |
|---|---|---|---|
pdfx1a |
PDF/X-1a:2001 | Not allowed: pages using it are flattened into images | 1.3 |
pdfx3 |
PDF/X-3:2002 | Not allowed: pages using it are flattened into images | 1.3 |
pdfx4 |
PDF/X-4 | Kept | 1.6 |
Transparency with PDF/X-1a and PDF/X-3
PDF/X-1a and PDF/X-3 do not allow transparency: soft shadows, semi-transparent shapes, images with a transparent background, blend modes. When the PDF uses any, the pages using it are flattened into images. The job still completes, and its warnings array says so with code 20048:
"warnings": [
{
"source": "conversion",
"code": 20048,
"message": "PDF/X-1a and PDF/X-3 do not allow transparency: the pages using it have been flattened into images.",
"details": null
}
]
On a flattened page the text is part of the image: it can no longer be selected, searched or edited. When that matters, choose pdfx4, which keeps transparency and text as they are.
Colour profile
A printer prints with cyan, magenta, yellow and black ink, on a given paper, under a given standard printing condition. color_profile names that condition: every colour of the PDF, RGB and grey included, is converted to CMYK with its output profile, and the file records the condition as its output intent, which the printer's software reads.
color_profile |
Profile | Output intent in the file | Use it for |
|---|---|---|---|
gracol2006 |
Coated GRACoL 2006 (ISO 12647-2:2004) | CGATS TR 006 |
Commercial printing in North America |
fogra39 |
Coated FOGRA39 (ISO 12647-2:2004) | FOGRA39 |
Coated paper in Europe |
Bleed
Bleed is the margin a printer trims off after printing, so that a picture or a background colour that runs to the edge of the page leaves no white line. Set bleed_mm to the bleed your printer asks for, usually 3 to 5 mm.
- The bleed is added on every side of every page. The content keeps its size and position, so an A4 page with 3 mm of bleed grows from 595 × 842 points to 612.01 × 859.01 points.
- The TrimBox of each page records where to cut: it stays the original page size. The MediaBox and the BleedBox include the bleed.
- The page edges are mirrored into the bleed, so no white strip shows after trimming even when the content stops at the page edge.
- A page that already has enough bleed of its own beyond its TrimBox keeps it.
Printer preset: Gelato
printer_preset applies the settings a print service asks for in one value. gelato gives PDF/X-4, gracol2006 and 4 mm of bleed:
curl -X POST "https://api.api2convert.com/v2/jobs" \
-H "x-api2convert-api-key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"type": "remote",
"source": "https://example-files.online-convert.com/document/pdf/example.pdf"
}
],
"conversion": [
{
"category": "operation",
"target": "convert-pdfx",
"options": {
"printer_preset": "gelato"
}
}
]
}'Each of the three other options still overrides the preset when you send it. Gelato asks for 3 mm of bleed on photobooks, for example:
curl -X POST "https://api.api2convert.com/v2/jobs" \
-H "x-api2convert-api-key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"type": "remote",
"source": "https://example-files.online-convert.com/document/pdf/example.pdf"
}
],
"conversion": [
{
"category": "operation",
"target": "convert-pdfx",
"options": {
"printer_preset": "gelato",
"bleed_mm": 3
}
}
]
}'| Options sent | Standard | Colour profile | Bleed |
|---|---|---|---|
"printer_preset": "gelato" |
PDF/X-4 | Coated GRACoL 2006 | 4 mm |
"printer_preset": "gelato", "bleed_mm": 3 |
PDF/X-4 | Coated GRACoL 2006 | 3 mm |
"printer_preset": "gelato", "color_profile": "fogra39" |
PDF/X-4 | Coated FOGRA39 | 4 mm |
| no options | PDF/X-4 | Coated GRACoL 2006 | none |
When a file cannot be converted
A file that cannot become a valid PDF/X file is never delivered: the job ends failed, with no output, and its errors array says why. See Errors & warnings for how errors are reported.
| Code | When | What to do |
|---|---|---|
6002 |
The PDF needs a password to be opened. Message: The file is password protected. Please, provide the password. | Send the password with the input: "credentials": { "decrypt_password": "…" } on a remote input, or a decrypt_password form field next to the file on a direct upload. See Importing files. PDF/X does not allow encryption, so the converted file has no password. |
6112 |
A font of the PDF does not allow embedding (a licence restriction in the font itself), while every PDF/X file must embed all its fonts. The error's details.fonts lists the fonts concerned. |
Replace the font, or convert the text to outlines, and send the file again. |
6113 |
The converted file does not pass the PDF/X check run before delivery. Message: The file cannot be converted to the selected PDF/X standard. | Try another standard; pdfx4 is the least restrictive. |
6004 |
The input is not a PDF. | Convert the file to PDF first. |
A remote input protected by a password, with its password:
"input": [
{
"type": "remote",
"source": "https://example-files.online-convert.com/document/pdf/example_protected.pdf",
"credentials": { "decrypt_password": "online-convert.com" }
}
]
A font error looks like this:
"errors": [
{
"source": "conversion",
"code": 6112,
"message": "The file uses a font whose license does not allow embedding it, but a PDF/X file must embed all its fonts. Please replace the font or convert the text to outlines and try again.",
"details": { "fonts": ["DejaVuSans-Bold"] }
}
]
Related guides
For archival PDF/A files, booklets and other PDF operations, see PDF operations. Every target and its current options are in the formats explorer.
Live options
Loading options…