Skip to main content

jamframe (Python)

The Python client for the JamFrame API: render your templates to images, carousels, PDFs and MP4 videos, design new templates with AI, run workflows, post to social accounts and read their analytics, and verify webhooks.

  • Python 3.9 or later. One dependency: httpx.
  • Sync (Client) and async (AsyncClient) clients with the same methods.
  • Fully typed (py.typed, TypedDict for every API shape, mypy --strict clean).
  • Retries 429s (honouring Retry-After) and, for idempotent calls only, 5xx answers, connection errors and timeouts.

API reference: app.jamframe.com/docs/api (the OpenAPI spec is app.jamframe.com/openapi.yaml). The Node.js SDK has the same surface.

Install

pip install jamframe

Quick start

Create an API key in the app under Developers → API Keys (it starts with jf_live_), then:

from jamframe import Client

client = Client(api_key="jf_live_...")  # or set JAMFRAME_API_KEY

result = client.render(
    "clx8m2k3p0001abcd1234efgh",            # a template id (yours or a library one)
    {"title": "Summer sale ends Sunday", "title.color": "#FF4D4F"},
    response={"format": "png", "scale": 2},
)
print(result["data"]["content"])        # the image URL
print(result["data"]["credits"])        # 1
print(result["warnings"])               # e.g. modification keys that matched nothing

Client() with no arguments reads JAMFRAME_API_KEY and, if set, JAMFRAME_BASE_URL. base_url is the API's origin (https://api.jamframe.com) or its root (…/v1); both work, and so does the older https://app.jamframe.com/api/v1.

Use it as a context manager (or call close()) to release connections:

with Client() as client:
    print(client.whoami())  # {'workspaceId': '…', 'username': 'Jane Doe'}

Templates

# Your workspace's templates, newest first (one page).
page = client.designs.list(limit=25)
page["designs"], page["pagination"]["nextCursor"]

# Every template, page after page.
for design in client.designs.iter():
    print(design["id"], design["name"], design["orientation"])

# The template library (ready-made templates any workspace can render).
for design in client.designs.iter(source="library"):
    ...

# A picker's search box: names containing the text, ignoring case (either source).
# Each design has its page count and `animated` (a video template: render it as mp4).
for design in client.designs.iter(source="library", q="reel"):
    print(design["name"], design["pages"], "video" if design["animated"] else "still")

# What a template takes: parameters (keys for `modifications`), page count, saved sizes.
detail = client.designs.get("clx8m2k3p0002abcd1234efgh")
for p in detail["parameters"]:
    print(p["key"], p["type"], p["pages"], p["example"])

Modification keys: title sets every layer (and {{title}} placeholder) with that key, page2@title only on page 2, title.color overrides a style property, page2@title.color both. See the API reference for the full list (fontSize, hidden, fill, audio, audio.volume, subtitles, …).

Design a template with AI

# Waits for the design (usually 10–40 s); 15 to 30 AI credits, refunded if it fails.
job = client.designs.generate(
    "Announce our summer sale, 30% off everything this weekend. Bold and playful.",
    size="instagram-portrait",   # or "linkedin-carousel" with pages=5, or "1200x630"
    # brand=False, or {"colors": ["#0b1f4d", "#ff6b5b"], "fonts": ["Poppins"]}; default: your brand library
)
job["design"]["id"]          # render it like any other template
job["design"]["parameters"]  # [{'key': 'title', …}, {'key': 'photo', …}]
job["design"]["editorUrl"]   # open it in the editor

# Or start it and come back later (webhook_url= is called when it ends).
started = client.designs.generate_async("A teaser video for our app launch", video=True)
done = client.design_jobs.wait(started["jobId"])

A failed generation raises DesignJobFailedError (.code, .message, .job).

Rendering

Credits: 1 per image or PDF page, 1 per second of video (rounded up), charged only when a render succeeds.

# A carousel: one URL per page.
r = client.render("tpl_id", {"title": "5 ways to brew", "page2@title": "1. Grind fresh"},
                  response={"format": "jpeg", "quality": 90})
r["data"]["content"]           # ['https://…-p1.jpg', 'https://…-p2.jpg', …]

# A library template by its slug, as a PDF of pages 1 and 2, with links that work for an hour.
client.render("tool-quote-card-paper", {"quote": "Stay curious"},
              response={"format": "pdf", "includePages": [1, 2]}, expires_in=3600)

# Smart Resize: one size …
client.render("tpl_id", {"title": "Hi"}, response={"format": "png", "size": "story"})
# … or several in one call (content is one entry per size).
r = client.render("tpl_id", {"title": "Hi"}, response={"sizes": ["original", "story", "1200x630"]})
for entry in r["data"]["content"]:
    print(entry["size"], entry["width"], entry["height"], entry.get("url") or entry.get("urls"))
r["data"]["urls"]              # every file's link in one list

# Translate every text layer with AI (AI credits; cached per text and language).
client.render("tpl_id", translate=True, lang="es", ai={"onError": "fallback"})

jamframe.file_urls(content) flattens any content (a URL, a list of URLs or the per-size entries) into a list of URLs. File links work for expires_in seconds (5 minutes by default, at most 7 days; data["expiresAt"] says until when).

Experimental, PDF only: response={"format": "pdf", "cmyk": True} (or {"profile": "gracol2013"}) converts the colours to CMYK for print, and "compress": True (or {"preset": "printer"}) makes the file smaller. Their options and output may still change.

Videos and render jobs

MP4 renders, and any render sent as async, run as render jobs.

# Simplest: render() waits. The API answers an MP4 within 90 s, or hands
# back a job, which render() then polls (up to wait_timeout seconds).
video = client.render("tpl_id", {"title": "New menu"}, response={"format": "mp4"})
video["data"]["content"], video["data"]["duration"]

# Queue it and get the job id at once …
job = client.render_async("tpl_id", {"title": "New menu"}, response={"format": "mp4"},
                          webhook_url="https://example.com/hooks/render-done")
job["jobId"]  # poll it, or wait for the webhook_url callback

# … poll it yourself …
client.render_jobs.get(job["jobId"])["progress"]  # 0 to 1

# … or wait for it (polls every 1 s, then 1.5x longer each time, at most 5 s).
done = client.render_jobs.wait(job["jobId"], timeout=600)
done["result"]["content"]

# Queue and wait in one call.
done = client.render_and_wait("tpl_id", {"title": "New menu"}, response={"format": "mp4"})

A failed job raises RenderJobFailedError (.code, .message, .job; failed renders cost nothing). Running past the timeout raises WaitTimeoutError (.job_id, .last_job); the job keeps running, so you can wait again.

The webhook_url callback is not signed. Treat it as a hint and fetch the job with render_jobs.get() before trusting it, or subscribe to the signed render.completed / render.failed webhook events instead.

Render log

page = client.renders.list(status="failed", limit=10)
page["totals"]["creditsRemaining"]          # this billing period
for render in client.renders.iter(design_id="tpl_id"):
    print(render["id"], render["status"], [o["url"] for o in render["outputs"]])

# One render by id (the `renderId` of a render, or of a job's `result`).
render = client.renders.get(result["data"]["renderId"])
render["status"], render["credits"], render["outputs"]

Signed URLs

A tamper-proof link that renders when opened, for <img src>, emails and og:image. Creating it is free; opening it renders (and caches) the image.

signed = client.signed_urls.create("tpl_id", {"title": "How we cut render times"},
                                   response={"format": "png"}, expires_in=30 * 24 * 3600)
signed["data"]["url"]

client.signed_urls.rotate_key()  # revoke every signed URL of the workspace

Workflows

Workflows render a template for each row of a Google Sheet, a CSV or XLSX file, an Airtable table or a webhook, and deliver the files. Build them in the app (or with workflows.create()), then run them from code.

workflows = client.workflows.list()

# Run one and wait for it to end; each row costs render credits.
run = client.workflows.run_and_wait(workflows[0]["id"], max_rows=2)   # a test run
run["status"]                             # 'succeeded', 'partial', 'failed' or 'canceled' (check it)
[row["urls"] for row in run["rows"]]      # each row's files

# A webhook-payload source: send the rows yourself.
client.workflows.run("wf_id", payload=[{"Quote": "Stay curious", "Author": "Ada"}])

for r in client.workflows.runs.iter("wf_id"):
    print(r["id"], r["status"])
client.workflows.runs.cancel("wf_id", "run_id")
client.workflows.update("wf_id", status="active")   # turns on its schedule or trigger

Social posts

Accounts are connected in the app, which shows the networks you can connect. Posting costs no credits; a template render costs the usual credits.

accounts = client.social.accounts.list()
ids = [a["id"] for a in accounts if a["status"] == "active"]

created = client.social.posts.create(
    template_id="tpl_id",
    modifications={"title": "Spring sale"},
    response={"format": "jpeg"},
    accounts=ids,
    caption="Spring sale starts today #sale",
    scheduled_at="2026-11-10T09:00",
    timezone="Europe/Paris",
    # options={"pinterest": {"boardId": "…"}, "tiktok": {"draft": True}, "buffer": {"mode": "next"}},
)
post = created["post"]          # created["checks"]: per-account warnings

client.social.posts.get(post["id"])["targets"]   # each account's status and permalink
client.social.posts.list(status="attention")      # failed or partly failed
client.social.posts.cancel(post["id"])
client.social.posts.retry(post["id"])             # or target_id="…" for one account

create() takes the API body as a dict, as keyword arguments, or both; template_id, render_id, media_urls and scheduled_at are accepted for templateId, renderId, mediaUrls and scheduledAt.

Analytics

import datetime

overview = client.social.analytics.overview(from_=datetime.date(2026, 10, 1), to="2026-10-31",
                                            platform=["instagram", "linkedin"])
overview["totals"]["impressions"], overview["change"]["engagement"]   # change in % from the period before
days = client.social.analytics.daily(from_="2026-10-01")["days"]
insights = client.social.analytics.insights()
insights["bestTimes"]["bestWeekday"], insights["bestTimes"]["bestHour"]

A metric is None when the platforms in scope don't report it. (from_ has an underscore because from is a Python keyword.)

AI tools

from pathlib import Path

# Cut the subject out of a picture (a URL or a file); a transparent PNG in your brand library. 1 AI credit.
cutout = client.ai.remove_background(file=Path("product.jpg"))
client.render("tpl_id", {"photo": cutout["url"]})

# Subtitles from speech (a URL or a file, up to 100 MB). 1 AI credit per minute of audio.
subs = client.ai.transcribe(url="https://example.com/voiceover.mp3", style="short")
client.render("tpl_id", {"subtitles": subs["cues"]}, response={"format": "mp4"})

# Whether AI is available, the prices and your AI credits this period. Free.
client.ai.status()["credits"]["remaining"]

file= takes bytes, a pathlib.Path or a file opened in binary mode (open("product.jpg", "rb")).

Webhooks

Subscribe a URL to events (design.created, design.updated, design.deleted, render.completed, render.failed, social.post.published, social.post.failed, workflow.run.completed, workflow.run.failed):

created = client.webhooks.subscriptions.create(
    "https://example.com/hooks/jamframe", ["render.completed", "render.failed"]
)
secret = created["signingSecret"]   # shown once: store it
client.webhooks.subscriptions.test(created["subscription"]["id"], "render.completed")
client.webhooks.subscriptions.delete(created["subscription"]["id"])

Verify every delivery against the raw body:

# Flask
from flask import Flask, request, abort
from jamframe import WebhookSignatureError, construct_event

app = Flask(__name__)

@app.post("/hooks/jamframe")
def jamframe_hook():
    try:
        event = construct_event(request.get_data(), request.headers, SECRET)
    except WebhookSignatureError:
        abort(400)
    # Deliveries are at-least-once: deduplicate on request.headers["X-Webhook-Delivery"].
    if event["type"] == "render.completed":
        print(event["data"]["result"]["content"])
    return "", 204
# FastAPI
from fastapi import FastAPI, HTTPException, Request
from jamframe import verify_signature

app = FastAPI()

@app.post("/hooks/jamframe")
async def jamframe_hook(request: Request):
    body = await request.body()
    if not verify_signature(body, request.headers.get("x-webhook-signature", ""), SECRET):
        raise HTTPException(400)
    ...

verify_signature(payload, header, secret, tolerance=300) returns a bool; construct_event raises WebhookSignatureError and returns the parsed event. header is the X-Webhook-Signature value or the request's headers; secret may be a list (old and new while you rotate). Signatures older or newer than tolerance seconds are refused (replay protection).

Errors

Every error answer raises a subclass of jamframe.APIError with status, code (the API's error, e.g. QUOTA_EXCEEDED), message (safe to show to users) and detail:

Status Exception Typical code
400 BadRequestError VALIDATION_ERROR, INVALID_REQUEST, WEBHOOK_URL_INVALID
401 AuthenticationError MISSING_API_KEY, INVALID_API_KEY, EXPIRED_API_KEY
402 PaymentRequiredError QUOTA_EXCEEDED, WORKSPACE_QUOTA_EXCEEDED, AI_CREDITS_EXCEEDED, PLAN_LIMIT_EXCEEDED, WEBHOOK_LIMIT_REACHED
403 PermissionDeniedError ORG_ON_HOLD, ORG_SUSPENDED
404 NotFoundError NOT_FOUND
409 ConflictError CONFLICT
422 UnprocessableEntityError VALIDATION_ERROR (a media URL that won't load), AI_CONTENT_REFUSED, AI_BAD_REQUEST
429 RateLimitError (.retry_after) RATE_LIMITED, AI_RATE_LIMITED
5xx InternalServerError INTERNAL, AI_BAD_OUTPUT, AI_UPSTREAM_ERROR, AI_UNAVAILABLE, VIDEO_UNAVAILABLE, AI_TIMEOUT

A body that isn't the API's JSON envelope (a proxy's HTML page) still raises the right class, with code HTTP_<status>. Network failures raise APIConnectionError, timeouts APITimeoutError. A failed render job raises RenderJobFailedError, a failed AI design DesignJobFailedError, a wait past its timeout WaitTimeoutError. Everything derives from jamframe.SDKError.

from jamframe import PaymentRequiredError, BadRequestError

try:
    client.render("tpl_id", {"titel": "typo is a warning, not an error"})
except PaymentRequiredError as e:
    print("Out of credits:", e.detail.get("remaining"))
except BadRequestError as e:
    print(e.code, e.message, e.detail.get("issues"))

Retries and timeouts

  • 429 is retried for every call (max_retries, default 2): the rate limiter refuses a request before anything happens. The client waits for Retry-After (or detail.retryAfter); if that's over 60 s it raises RateLimitError instead.
  • 5xx, connection errors and timeouts are retried only for idempotent calls: reads, deletes, whoami(), signed_urls.create() and workflows.update(). A render, an AI call, a social post, a workflow run or a subscription isn't retried: it may have happened before the error.
  • Backoff is 0.5 s, 1 s, 2 s … (at most 8 s), with jitter.
  • timeout (default 120 s) is per HTTP request. It must cover a synchronous MP4, which the API holds for up to 90 s. Waiting for a job has its own timeout / wait_timeout (default 600 s).
client = Client(timeout=30, max_retries=4, user_agent="my-app/1.2")

user_agent is prepended to jamframe-python/<version>. Pass http_client=httpx.Client(...) (or httpx.AsyncClient for the async client) for proxies, custom TLS or transports; the SDK won't close a client you pass in.

Async

import asyncio
from jamframe import AsyncClient

async def main():
    async with AsyncClient() as client:
        job = await client.render_and_wait("tpl_id", {"title": "Hi"}, response={"format": "mp4"})
        async for design in client.designs.iter(source="library"):
            print(design["name"])

asyncio.run(main())

Why httpx

One dependency buys a lot here: the same request code drives a sync and an async client, timeouts are real (connect, read, write and pool), connections are pooled and kept alive across calls, and httpx.MockTransport lets the tests run the real client code against a fake API with no server. The standard library's urllib has no async client, no keep-alive pooling and coarse timeouts, so it would mean either a sync-only SDK or a second HTTP stack for async.

Development

uv sync --extra dev    # or: python -m venv .venv && pip install -e ".[dev]"
uv run pytest          # unit tests (no network: httpx.MockTransport)
uv run mypy            # strict type check of src/jamframe

tests/test_spec.py checks the SDK against the API spec in spec/openapi.yaml: every endpoint has a method (or is skipped on purpose), the types have exactly the spec's fields and enum values, and the async client has the same methods as the sync one. python scripts/update_spec.py downloads the live spec; CI does that every Monday, so a new API feature shows up as a failing check.

The live smoke test runs only when JAMFRAME_SMOKE_API_KEY is set. It renders 2 PNGs of a library template (2 credits), lists designs and renders, signs a URL, reads AI status, workflows and analytics, creates and deletes a webhook subscription, and posts to an active sandbox social account if the workspace has one:

JAMFRAME_SMOKE_API_KEY=jf_live_... JAMFRAME_SMOKE_BASE_URL=https://api.jamframe.com \
  uv run pytest tests/test_live_smoke.py -s

Use a throwaway key and revoke it afterwards.

Releasing

  1. Update version in pyproject.toml and src/jamframe/_version.py (a test checks they match) and add the release to CHANGELOG.md.
  2. Commit, then tag the commit with the bare version (0.1.1) and push the tag.
  3. publish.yml runs the checks, builds, publishes to TestPyPI, then (after approval in the pypi environment) to PyPI, through trusted publishing: no token is stored anywhere.

License

MIT

Metadata

Release files for jamframe 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jamframe 0.1.0
File Size Uploaded Provenance Actions
jamframe-0.1.0.tar.gz 123.3 kB With provenance Details for jamframe-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jamframe 0.1.0
File Interpreter ABI Platform Actions
jamframe-0.1.0-py3-none-any.whl Python 3 none any Details for jamframe-0.1.0-py3-none-any.whl

Total release size: 172.0 kB

Release files / jamframe-0.1.0.tar.gz

Download URL jamframe-0.1.0.tar.gz
Size 123.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4592ecca99b2af804e5c78d2340e93d1f69603b237c4cd696ed4b9b45d76bbe1
BLAKE2b-256 checksum
How to use checksums
23bbcd12530f3f85ce909c0f1fc42e8c7d2a4d6e19b368bf528529b80d353fb3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / jamframe-0.1.0-py3-none-any.whl

Download URL jamframe-0.1.0-py3-none-any.whl
Size 48.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0446fa033cdde35807cb50f9e8ecf69bb5efcc64b6a83fd149595bbeaa56cf8e
BLAKE2b-256 checksum
How to use checksums
9a3e87fbe9c6fa2df901353fdf9d8104737ead4b3d1690a6c957a0b6050c2bfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for jamframe 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jamframe-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page