Set PDF and image options

Use with your agent

Read https://thirds.ai/docs/outputs and help me choose PDF or image settings for my design and prepare a request with the right layout, fonts, and dimensions.

Set up your design for a printed page or a fixed image size. These options control paper, page breaks, fonts, headers, and image capture. For your first API request, start with Create your first PDF.

Set a PDF page

Put PDF settings in the pdf object of a POST /v1/pdf request. The default is A4 portrait with zero margins, backgrounds on, and a scale of 1.

Choose a named format, such as A4 or Letter, or set both width and height. Use one of these methods per request. Include a unit such as mm, cm, in, or px with each length. Set landscape: true for a wide page.

The request sets the paper size. A CSS @page size does not override it, so keep your CSS and request settings in agreement. PDF output uses print styles. Check any @media print rules in HTML you import.

Keep content on the right page

Use CSS page breaks to keep a heading with its text or start a new section. A block must fit on one page before break-inside: avoid can keep it together.

h1,
h2 {
  break-after: avoid;
}
tr,
.total {
  break-inside: avoid;
}
.new-page {
  break-before: page;
}
p {
  orphans: 3;
  widows: 3;
}

Test an invoice with no items, one item, many items, and a long item name. Let rows grow with their text. A fixed row height or overflow: hidden can hide values. Use a real table with thead and tbody for invoice items. Compute amounts in your app and pass the results as template data.

Add headers and page numbers

Headers and footers sit outside the document body. Turn them on with display_header_footer and leave enough top and bottom margin for them. Give each template its own styles. They do not inherit body styles, and their scripts do not run.

This request makes two pages with the same header and a numbered footer:

{
  "html": "<!doctype html><html lang='en'><head><meta charset='utf-8'><style>body{margin:0;font:15px/1.55 sans-serif}article{break-after:page}article:last-child{break-after:auto}</style></head><body><article><h1>Quarterly report</h1><p>Orders completed: 24</p></article><article><h1>Next steps</h1><p>Send the report to your team.</p></article></body></html>",
  "pdf": {
    "format": "A4",
    "margins": {
      "top": "20mm",
      "right": "12mm",
      "bottom": "20mm",
      "left": "12mm"
    },
    "display_header_footer": true,
    "header_template": "<span style='font-size:9px;width:100%;text-align:center'>Quarterly report</span>",
    "footer_template": "<span style='font-size:9px;width:100%;text-align:center'><span class='pageNumber'></span> / <span class='totalPages'></span></span>"
  }
}

The pageNumber and totalPages classes insert the current page and total page count. Keep header and footer templates small. Put logos and complex layouts in the document body when possible.

Use the fonts and assets you need

Include <meta charset="utf-8"> for currency symbols and accented names. Set a font family in CSS and test each language you use. thirds.ai cannot use a font just because it is installed on your laptop.

Use your brand kit for saved designs. For direct HTML, load a licensed web font with @font-face or choose a generic family such as sans-serif. Images can use an uploaded private reference, a public HTTPS URL, or a supported inline data format. thirds.ai cannot read your local files through relative paths or file:// URLs.

thirds.ai checks the addresses of fonts, images, and styles. It rejects private network hosts and unsafe redirects. If a remote font or image changes, later output can change even with the same HTML. Keep asset versions fixed when you need a stable layout. See retries and limits if an asset fails to load.

Upload an image once

Upload a still PNG, JPEG, or WebP file before you save or render a template. Send the raw file bytes with its media type:

curl https://thirds.ai/v1/image-assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

The reply gives you a reference, such as asset://asset_0123456789abcdef0123456789abcdef, plus the image width and height. Use that exact reference in an HTML body image src. You can also pass it as template data, for example <img src="{{ photo }}" alt="Product"> with photo set to the reference.

Uploads are private and free. The reference works only for your account. It stays fixed so saved versions and later renders use the same bytes. An upload can be up to 10 MiB. Images and brand files share a 100-file, 100 MiB account limit. One render can use up to 20 MiB of image bytes. A missing or foreign reference fails before a render job or charge. Put uploaded images in the document body; private references do not work in PDF header or footer templates. See the API reference for the full limits.

In the editor, choose Image, then Upload image. Uploaded images show in the design canvas. Remote image URLs stay hidden in browser previews; exports fetch them through the protected render service.

Make a static image

Use POST /v1/image with image.format, image.width, and image.height. thirds.ai captures the rectangle you specify at device scale 1. It does not scroll to capture more content. Anything beyond that rectangle falls outside the image.

{
  "html": "<!doctype html><html lang='en'><head><meta charset='utf-8'><style>*{box-sizing:border-box}body{margin:0;background:#0a46ff;color:white;font:32px/1.4 sans-serif}main{padding:64px}h1{font-size:64px;margin:0 0 24px}</style></head><body><main><h1>September report</h1><p>24 orders completed</p></main></body></html>",
  "image": {
    "format": "png",
    "width": 1200,
    "height": 630,
    "transparent": false
  }
}

Format	Choose it for	Options
`png`	Sharp text and flat colours	Supports transparency. Omit `quality`.
`jpeg`	Photos	`quality` is 1 to 100 and defaults to 80. Transparency must be false.
`webp`	Smaller images with text or photos	`quality` is 1 to 100 and defaults to 80. Supports transparency.

The default size is 1280 by 720 pixels. Width can be 320 to 7680 pixels, and height can be 200 to 4320 pixels. The total must also fit the pixel limit. For transparent PNG or WebP, set transparent: true and leave the HTML background transparent too.

Finish JavaScript before capture

JavaScript is off by default. Send finished HTML for invoices and other fixed data when you can. If a chart needs JavaScript, set javascript.mode to enabled. Set the ready marker after the chart is complete:

document.documentElement.dataset.thirdsRenderReady = "true";

The renderer waits up to two seconds for this marker, then stops scripts once it is ready. Set the marker only after fonts, data, and chart drawing finish. If the marker is missing, the render fails with javascript_readiness_timeout. The renderer blocks browser navigation, popups, nested frames, and background workers.

Next, download the finished file. See credits and billing for output and preview costs. If you are replacing wkhtmltopdf, follow the migration guide.

Start free