Render images and PDFs

POST /v1/render makes files from a template. You send the template id and the values to fill in. The answer comes when the files are ready, with a link to each one.

The request

POST https://api.jamframe.com/v1/render

Every field of response is optional:

To fill layers with AI or translate the text while rendering, see AI at render time.

Render one image

This request changes three layers and the color of one of them, and makes a PNG at twice the size:

curl https://api.jamframe.com/v1/render \
  -H "Authorization: Bearer $JAMFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clx8m2k3p0001abcd1234efgh",
    "modifications": {
      "title": "Summer sale ends Sunday",
      "subline": "Up to 50% off everything",
      "photo": "https://example.com/images/beach.jpg",
      "title.color": "#FF4D4F"
    },
    "response": { "format": "png", "scale": 2 }
  }'

const res = await fetch("https://api.jamframe.com/v1/render", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JAMFRAME_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateId: "clx8m2k3p0001abcd1234efgh",
    modifications: {
      title: "Summer sale ends Sunday",
      subline: "Up to 50% off everything",
      photo: "https://example.com/images/beach.jpg",
      "title.color": "#FF4D4F",
    },
    response: { format: "png", scale: 2 },
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error}: ${body.message}`);
console.log(body.data.content); // the link to the image

import os
import requests

res = requests.post(
    "https://api.jamframe.com/v1/render",
    headers={"Authorization": f"Bearer {os.environ['JAMFRAME_API_KEY']}"},
    json={
        "templateId": "clx8m2k3p0001abcd1234efgh",
        "modifications": {
            "title": "Summer sale ends Sunday",
            "subline": "Up to 50% off everything",
            "photo": "https://example.com/images/beach.jpg",
            "title.color": "#FF4D4F",
        },
        "response": {"format": "png", "scale": 2},
    },
)
res.raise_for_status()
print(res.json()["data"]["content"])  # the link to the image

The answer:

{
  "data": {
    "content": "https://cdn.jamframe.com/renders/ws_abc123/5f0c6b0e.png?Expires=…",
    "expiresAt": "2026-11-14T12:05:00.000Z",
    "type": "url",
    "format": "png",
    "pages": [1],
    "credits": 1,
    "renderId": "clx8n0q1r0004abcd1234efgh",
    "responseTime": 1840
  }
}

The answer

The most common warning is a key that matched nothing in the template, often a typo:

{
  "data": { "content": "https://cdn.jamframe.com/renders/…", "credits": 1 },
  "warnings": ["Unknown modification keys (no matching layer or {{placeholder}}): titel"]
}

Carousels: several pages

A template with several pages makes one image per page. content is then an array of links, in page order, and each image costs one credit. To give each page its own text, put pageN@ in front of a key:

{
  "templateId": "clx8m2k3p0002abcd1234efgh",
  "modifications": {
    "brand": "Acme Coffee",
    "title": "5 ways to brew better coffee",
    "page2@title": "1. Grind just before brewing",
    "page3@title": "2. Weigh your beans",
    "[email protected]": 56
  },
  "response": { "format": "jpeg", "quality": 90 }
}

{
  "data": {
    "content": [
      "https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-p1.jpg?Expires=…",
      "https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-p2.jpg?Expires=…",
      "https://cdn.jamframe.com/renders/ws_abc123/9a1e2b3c-p3.jpg?Expires=…"
    ],
    "expiresAt": "2026-11-14T12:05:00.000Z",
    "type": "url",
    "format": "jpeg",
    "pages": [1, 2, 3],
    "credits": 3,
    "renderId": "clx8n0q1r0005abcd1234efgh",
    "responseTime": 4210
  }
}

• A render can include at most 20 pages.
• includePages picks pages, such as [2, 3]. The files always come out in the template’s page order.
• A page number the template doesn’t have is a 400.

To design carousels, see Pages and carousels.

PDFs

"format": "pdf" makes one PDF with every rendered page, in order. content is always one link, and each page costs one credit. This request makes a PDF of pages 1 and 2, with a link that works for an hour:

{
  "templateId": "clx8m2k3p0003abcd1234efgh",
  "modifications": { "customer_name": "Jane Doe" },
  "response": { "format": "pdf", "includePages": [1, 2] },
  "expiresIn": 3600
}

Each PDF page has the template’s size. A template made from the A4 or US Letter size prints on that paper size. scale and quality don’t apply to PDFs.

Base64 instead of links

With "type": "base64", content holds each file’s bytes as base64, with no data: prefix. Nothing is stored, so there are no links and no expiresAt. Decode the string and save it.

• Don’t send expiresIn with base64. That’s a 400.
• Base64 works only for renders that wait for the answer, not with async or sizes.
• Big files make big answers. For large PDFs and carousels, use links.

How long links and files last

• Links work for expiresIn seconds: 5 minutes by default, at most 7 days. expiresAt says until when. After that, a link answers 403.
• Files of an API render are deleted 8 days after the render, so a link never outlives its file. See How long files last.
• To keep a file, download it and store it yourself.
• GET /v1/renders/{id} gives fresh links to a past render’s files, for as long as the files exist. See Templates and renders.

Images in a render

Image URLs, in the template or in modifications, must be public http:// or https:// addresses. data: URLs work too.

• An address on a private network, such as localhost or 10.0.0.5, is refused with 400 before anything renders.
• If an image can’t be loaded, the render fails with 422 and the message names the URL. This happens when the image isn’t public, isn’t an image, its server doesn’t answer in time, or its name leads to a private address. No credits are charged.

Limits

Credits

• One credit per image, or per PDF page. A single image costs 1, a 5-page carousel 5, a 3-page PDF 3. With sizes, it’s 1 per page per size.
• Library templates cost the same as your own.
• Credits are charged only when the render works. A failed render is free.
• If your organization can’t pay for a render, it’s refused before it starts, with 402 QUOTA_EXCEEDED. If an admin has capped this workspace’s share of credits, it’s 402 WORKSPACE_QUOTA_EXCEEDED.

See Credits.

Common errors

See Errors for every code.

Related

• Every way to change a template: Modification keys.
• Render without waiting: Async renders.
• The same design at other sizes: Smart Resize.
• All fields and examples: the Render endpoints in the API reference (opens in a new tab).