Skip to content
JamFrame
Docs menu

Node.js and Python SDKs

Install the official JamFrame libraries for Node.js and Python, and render templates, wait for videos, design templates with AI, run workflows, post to social accounts and check webhooks in a few lines.

JamFrame has two official libraries, both called jamframe: one for Node.js and TypeScript on npm, one for Python on PyPI. They call the same REST API as the other pages here, and save you the plumbing: they send your key, wait for videos, page through lists, retry when it’s safe, and turn errors into exceptions you can catch.

Both are free and open source (MIT), on GitHub: jamframe-node and jamframe-python. Each repository’s README lists every method.

Install

npm install jamframe
pip install jamframe
  • Node.js: Node 18.17 or later. The package is an ES module with TypeScript types, and has no other packages to install.
  • Python: Python 3.9 or later. It has a normal client and an async one with the same methods, and needs one other package, httpx, which pip installs for you.

Set your key

Create an API key in the app, under Developers → API Keys (see API keys). Put it in the JAMFRAME_API_KEY environment variable on your server. Both libraries read it from there, so it stays out of your code.

export JAMFRAME_API_KEY=jf_live_…

Render a template

import { JamFrame } from "jamframe";

const client = new JamFrame(); // reads JAMFRAME_API_KEY

const { data, warnings } = await client.render({
  templateId: "clx8m2k3p0001abcd1234efgh",
  modifications: { title: "Summer sale ends Sunday", "title.color": "#FF4D4F" },
  response: { format: "png", scale: 2 },
});

console.log(data.content); // the file URL
console.log(warnings);     // e.g. keys that matched nothing
from jamframe import Client

client = Client()  # reads JAMFRAME_API_KEY

result = client.render(
    "clx8m2k3p0001abcd1234efgh",
    {"title": "Summer sale ends Sunday", "title.color": "#FF4D4F"},
    response={"format": "png", "scale": 2},
)

print(result["data"]["content"])  # the file URL
print(result["warnings"])         # e.g. keys that matched nothing

modifications and response work as in Render images, PDFs and videos and Modifications. A carousel gives one URL per page, and a PDF one URL.

Videos and long renders

render() waits for videos too. If the API hands back a render job, the library checks it after 1 second, then 1.5 times longer each time (at most 5 seconds apart), for up to 10 minutes, and gives you the finished file.

const video = await client.render(
  { templateId: "clx8m2k3p0002abcd1234efgh", response: { format: "mp4" } },
  { onProgress: (job) => console.log(Math.round(job.progress * 100), "%") },
);
console.log(video.data.content, video.data.duration);

// Or start it and come back later:
const { jobId } = await client.renderAsync({ templateId: "clx8m2k3p0002abcd1234efgh", response: { format: "mp4" } });
const done = await client.renderJobs.wait(jobId);
video = client.render("clx8m2k3p0002abcd1234efgh", response={"format": "mp4"})
print(video["data"]["content"], video["data"]["duration"])

# Or start it and come back later:
job = client.render_async("clx8m2k3p0002abcd1234efgh", response={"format": "mp4"})
done = client.render_jobs.wait(job["jobId"])

A failed render raises RenderJobFailedError and costs nothing. If the wait runs out, you get WaitTimeoutError, but the job keeps running and you can wait again. See Async renders.

Find templates

// Every template in your workspace, page after page.
for await (const design of client.designs.iterate()) console.log(design.id, design.name);

// Library templates whose name contains "quote".
for await (const design of client.designs.iterate({ source: "library", q: "quote" })) console.log(design.name);

// What one template takes: its parameters (the keys for modifications) and saved sizes.
const template = await client.designs.get("clx8m2k3p0001abcd1234efgh");
console.log(template.parameters);
# Every template in your workspace, page after page.
for design in client.designs.iter():
    print(design["id"], design["name"])

# Library templates whose name contains "quote".
for design in client.designs.iter(source="library", q="quote"):
    print(design["name"])

# What one template takes: its parameters (the keys for modifications) and saved sizes.
template = client.designs.get("clx8m2k3p0001abcd1234efgh")
print(template["parameters"])

Design a template with AI

The call waits for the design (usually 10 to 40 seconds) and saves it in your workspace, with your brand library’s colours, fonts and logo. Each design costs 15 to 30 AI credits, refunded if it fails. See Generate a template.

const job = await client.designs.generate({
  prompt: "Announce our summer sale, 30% off everything this weekend. Bold and playful.",
  size: "instagram-portrait",
});
console.log(job.design.id, job.design.editorUrl);
job = client.designs.generate(
    "Announce our summer sale, 30% off everything this weekend. Bold and playful.",
    size="instagram-portrait",
)
print(job["design"]["id"], job["design"]["editorUrl"])

Run a workflow

Run a workflow you built in the app, and wait until every row is done. Each row costs the usual render credits. A run that fails doesn’t raise an error, so check status. See Workflows API.

const run = await client.workflows.runAndWait("clx8n0q1r0004abcd1234efgh", { maxRows: 2 });
console.log(run.status); // succeeded, partial, failed or canceled
for (const row of run.rows) console.log(row.index, row.urls);
run = client.workflows.run_and_wait("clx8n0q1r0004abcd1234efgh", max_rows=2)
print(run["status"])  # succeeded, partial, failed or canceled
for row in run["rows"]:
    print(row["index"], row["urls"])

maxRows (Python: max_rows) renders only the first rows, for a test run.

Post to social accounts

Connect the accounts in the app first (see Connect accounts). Posting costs no credits; the render costs the usual credits.

const accounts = await client.social.accounts.list();
const { post } = await client.social.posts.create({
  templateId: "clx8m2k3p0001abcd1234efgh",
  modifications: { title: "Spring sale" },
  accounts: [accounts[0].id],
  caption: "Spring sale starts today",
  scheduledAt: "2026-12-01T09:00",
  timezone: "Europe/Paris",
});

// How the posts did, for the last 28 days.
const overview = await client.social.analytics.overview();
console.log(overview.totals.impressions);
accounts = client.social.accounts.list()
created = client.social.posts.create(
    template_id="clx8m2k3p0001abcd1234efgh",
    modifications={"title": "Spring sale"},
    accounts=[accounts[0]["id"]],
    caption="Spring sale starts today",
    scheduled_at="2026-12-01T09:00",
    timezone="Europe/Paris",
)

# How the posts did, for the last 28 days.
overview = client.social.analytics.overview()
print(overview["totals"]["impressions"])

Check webhooks

Pass the raw request body, the request headers and your signing secret. You get the event back, or an error if the signature doesn’t match. See Webhooks.

import { constructWebhookEvent } from "jamframe";

// In your route, with the raw body (for Express: express.raw({ type: "application/json" })).
const event = constructWebhookEvent(req.body, req.headers, process.env.JAMFRAME_WEBHOOK_SECRET);
if (event.type === "render.completed") console.log(event.data.result?.content);
from jamframe import construct_event

# In your view, with the raw body (Flask: request.get_data()).
event = construct_event(request.get_data(), request.headers, WEBHOOK_SECRET)
if event["type"] == "render.completed":
    print(event["data"]["result"]["content"])

Errors and retries

Every error from the API becomes an exception with the API’s code (such as QUOTA_EXCEEDED), its message and its detail. Each HTTP status has its own class, such as PaymentRequiredError for 402 and RateLimitError for 429. See Errors.

import { PaymentRequiredError } from "jamframe";

try {
  await client.render({ templateId: "clx8m2k3p0001abcd1234efgh" });
} catch (err) {
  if (err instanceof PaymentRequiredError) console.log("Out of credits:", err.code);
  else throw err;
}
from jamframe import PaymentRequiredError

try:
    client.render("clx8m2k3p0001abcd1234efgh")
except PaymentRequiredError as err:
    print("Out of credits:", err.code)

The libraries retry for you, but only when it can’t charge you twice:

  • Rate limits (429) are retried on every call, after the wait the API asks for. The rate limit stops a request before anything runs, so nothing happened the first time.
  • Server and network errors are retried only on calls that are safe to repeat, such as reads. Never on a render, an AI call, a social post or a workflow run: the first try may have worked.

Both retry twice by default. Change it with maxRetries (Python: max_retries) when you create the client.

Python’s async client

AsyncClient has the same methods as Client, for asyncio apps such as FastAPI:

import asyncio
from jamframe import AsyncClient

async def main():
    async with AsyncClient() as client:
        result = await client.render("clx8m2k3p0001abcd1234efgh", {"title": "Hello"})
        print(result["data"]["content"])

asyncio.run(main())

What next

Last updated

Still stuck?

Email [email protected] and a real person will reply. Tell us the template you were using and what you expected to happen.