Create your first PDF

Send a small piece of HTML and save the result as report.pdf. You need a verified account, an API key, one available credit, and curl. Follow API key setup if you do not have a key yet.

The commands use placeholder IDs and credentials. Replace YOUR_API_KEY with your key in a private terminal.

Each successful output costs one credit. Run a create command when you are ready to spend that credit. Choose your own Idempotency-Key for each output and reuse that key if you retry the same request. A new key means a new output.

Send HTML

curl --fail-with-body --silent --show-error https://thirds.ai/v1/pdf \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_PDF_REQUEST' \
  --data '{"html":"<h1>Quarterly report</h1><p>Ready to share.</p>"}'

The response contains an id and status. Keep the ID so you can check this render again. If status is succeeded, go to the download step. If it is queued or running, poll for the result. For failed or cancelled, follow recovery.

Wait or poll

The create request waits briefly for the result. If the render is still in progress, it returns 202. Add "wait":false to the JSON body if you want a response as soon as thirds.ai accepts the job. This changes the wait time, not the render.

Replace pdf_00000000000000000000000000000000 with the returned job ID.

curl --fail-with-body --silent --show-error \
  https://thirds.ai/v1/pdf/pdf_00000000000000000000000000000000 \
  -H 'Authorization: Bearer YOUR_API_KEY'

While the status is queued or running, wait between polls and stop at a deadline set by your app. Follow Retry-After if the API rate-limits a request. When you resume, check the same job instead of creating another one. Use webhooks if you want thirds.ai to notify your server when the result is ready.

Download the file

Once status is succeeded, copy download.url from the response. It is a path such as /v1/downloads/.... Add https://thirds.ai before the path, then use that URL in the command below. Anyone with this signed URL can download the file. The download command does not need your API key.

curl --fail --silent --show-error \
  'https://thirds.ai/v1/downloads/YOUR_SIGNED_DOWNLOAD_TOKEN' \
  --output report.pdf

Open report.pdf to check the result and keep your own copy before the file expires. If the download link expires first, read the job again for a fresh link. See download and retention rules.

Create an image

To make a 1200 by 630 pixel PNG, send this request. Use the returned ID to poll GET /v1/image/{id}, then download the signed URL as before. Save the file with a .png extension.

curl --fail-with-body --silent --show-error https://thirds.ai/v1/image \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_IMAGE_REQUEST' \
  --data '{"html":"<h1>Quarterly report</h1><p>Ready to share.</p>","image":{"format":"png","width":1200,"height":630},"wait":false}'

You can also choose jpeg or webp. Use the matching file extension. Read PDF and image options to set quality, backgrounds, fonts, and dimensions.

Reuse a saved template

Save a template when you want to use the same design with new data. This request saves the source and schema. It does not create an output or use AI credits.

curl --fail-with-body --silent --show-error https://thirds.ai/v1/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"source":"<h1>{{ title }}</h1>","schema":{"type":"object","properties":{"title":{"type":"string"}},"required":["title"],"additionalProperties":false}}'

Keep the returned template id and latest_version. Put the ID in the request below. Version 1 keeps the source you just saved, and each render can fill it with different data.

curl --fail-with-body --silent --show-error https://thirds.ai/v1/pdf \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_TEMPLATE_RENDER' \
  --data '{"template_id":"tpl_00000000000000000000000000000000","version":1,"data":{"title":"Quarterly report"}}'

Poll and download as before. Read templates and data for field syntax, schemas, and saved versions. You can also send html with placeholders and a data object in one render request. This fills the fields without saving a reusable template.

Create with words or a source image

To build a design in the studio, follow Design and edit a template. You can start with words or a source image, apply your brand kit, and edit the result before you publish. Use the published template ID in the request above. Read MCP setup to work through these steps with an agent.