Package Information
Documentation
n8n-nodes-jamframe
An n8n community node package for JamFrame: render images,
carousels, PDFs and MP4 videos from your templates, post them to connected
social accounts, run your JamFrame workflows, design templates and edit media
with AI, and start n8n workflows when a render job ends, a post goes out, a
template changes or a workflow run ends.
Not published yet. Check the package name
n8n-nodes-jamframe, thejamframe.comURLs and the GitHub repository URLs inpackage.jsonand
the codex files before the first publish (see Renaming): n8n stores node and
credential names in every saved workflow, so they can't change afterwards.
It contains:
| JamFrame node | Render a template; get or list past renders; get or wait for a render job; get, list and generate templates (AI); remove an image's background (AI); transcribe audio or video into subtitles (AI); list social accounts; create, get, list, cancel and retry social posts; social analytics; get, list and run workflows; get, list and cancel workflow runs |
| JamFrame Trigger node | Starts a workflow on render.completed, render.failed, social.post.published, social.post.failed, design.created, design.updated, design.deleted, workflow.run.completed or workflow.run.failed; subscribes and unsubscribes itself, and checks each delivery's signature |
| JamFrame API credentials | An API key and the API's base URL |
It talks to the API-key authenticated /v1 API only (the
API reference) and has no runtime
dependencies.
Install
Once the package is on npm:
- n8n UI (self-hosted, owner or admin): Settings → Community Nodes →
Install, entern8n-nodes-jamframe, accept the risk notice. Verified
community nodes can also be added from the nodes panel, including on n8n
Cloud. - Manually (queue mode, or a private build): in the n8n host or container,
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes && npm i n8n-nodes-jamframe,
then restart n8n.
To try an unpublished build, run npm run dev in this folder (see
Develop), or npm pack and install the .tgz the same way.
Credentials
JamFrame API:
- API Key: create one in the app under Developers → API Keys (keys start
withjf_live_). A key belongs to one workspace; everything the nodes do
happens in that workspace. - Base URL:
https://api.jamframe.com(the default), or your staging or
self-hosted address, without/v1.
n8n tests the credential with POST /v1/auth, which answers 200 for a
valid key.
The JamFrame node
Render → Render Template
POST /v1/render. Costs 1 credit per image or PDF page, 1 per second of
video, only when the render succeeds.
- Template: pick from the list (your workspace's templates first, then the
template library, labelledLibrary: …; type to search by name; video
templates sayvideo), or paste an ID (useful with expressions; a library
template's slug such astool-quote-card-paperworks too). Library
templates render like your own and are charged to your workspace. - Template Parameters: one field per parameter of the chosen template,
loaded fromGET /v1/designs/{id}(text, image/video/audio URLs, QR
values, shape colours,{{placeholders}}, subtitles). Empty fields keep the
template's own content. Switch the mapper to Map Automatically to take
values from input fields with the same names. - Additional Modifications: any other key, sent as it is and winning over
the fields above:page2@title(one page of a carousel),title.color,title.fontSize,badge.hidden,audio.volume,subtitles.style.position… - Format: PNG, JPEG, WebP (one file per page), PDF (one file), MP4 video
(one file; each page a scene; always a render job). - Resize (Smart Resize): One Size takes a size saved on the template,
a size name (story,square,portrait,landscape,widescreen,thumbnail,pin,original, or a preset such asinstagram-story) orWIDTHxHEIGHTin the Custom mode. Several Sizes renders up to 10
sizes in one call (images and PDF, not as a job; 1 credit per page per
size). - Run as Job: queue the render (
"async": true) and get a job ID at once. - Wait for Completion (default on): when the API answers with a job (a job
render, or an MP4 still rendering after 90 seconds), pollGET /v1/render-jobs/{id}after 1 s, then every ×1.5 up to 5 s, until it
ends; give up after Timeout (600 s by default; the job keeps running).
Off: output{ jobId, status }. - Options: Pages (
1, 3-4), Scale (1–3×), Quality (JPEG/WebP), Subtitles
File (MP4: also store an.srt/.vtt), Webhook URL (jobs: the API POSTs{ event, job }there when the job ends), Timeout, Download Files (each
file as binary datadata,data_1, …).
Output: the API's render result (content, format, pages, credits,renderId, responseTime, duration and subtitles for MP4) plus url
(the first file), urls (every file; with several sizes, every size's files in
order), warnings (e.g. modification keys that matched nothing) and jobId
when it ran as a job.
Render → Get / Get Many
The render log: GET /v1/renders/{id} and GET /v1/renders (newest first;
Filters: Status, Template ID; Return All / Limit). Renders made anywhere
are listed: this node, the app, signed and dynamic URLs, forms, workflows,
Zapier and Make. Each item has outputs (fresh file links that work for
5 minutes; files are kept 8 days) plus url and urls as above. Get can
also download the files as binary data. Free.
Render Job → Get / Wait
GET /v1/render-jobs/{id}: status (queued, running, succeeded,failed), progress, and the files (url, urls, result) once it
succeeded. Wait polls as above; a failed job fails the node with the job's
error (no credits are charged for it).
Template → Get / Get Many
GET /v1/designs/{id} (pages, parameters and saved sizes) andGET /v1/designs with Source = Workspace or Template Library
(?source=library), with Return All / Limit.
Template → Generate with AI
POST /v1/designs/generate. The design agent designs a new template from
your Prompt and saves it in the workspace, with parameter keys on the
layers a render changes (title, photo, cta…). Costs 5 AI credits,
refunded if it fails.
- Size: a preset (
instagram-story,linkedin-carousel,og-image…), a
short name (square,portrait,story,landscape) orWIDTHxHEIGHT;
1080x1350 when empty. - Brand: the workspace's brand kit (default), no brand, or custom colours,
fonts and a logo. - Wait for Completion (default on): a design takes 10–40 seconds; the API
waits about 25 seconds, then the node pollsGET /v1/designs/generate/{jobId}until it is saved (Timeout, 300 s by
default). Off: output{ jobId, status }at once. - Options: Name, Pages (1–10, a carousel), Video (an animated template),
Reference Image URL, Timeout.
Output: the job (message, changes, creditsCharged, design with its
parameters and editorUrl) plus templateId, ready for Render Template's
By ID mode ({{ $json.templateId }}).
Image → Remove Background
POST /v1/images/remove-background. Cuts the subject out onto a transparent
PNG and saves it in the workspace's brand library; url can go straight into
an image parameter of a render. Costs 1 AI credit (4 on a server without the
local cut-out model, where an image model redraws the subject).
- Input: a public URL, or a Binary File of the input item (e.g.
from Google Drive or an HTTP Request node), sent as a multipart upload. PNG,
JPEG, GIF or WebP up to 10 MB. - Options: Asset Name, Download Result (the PNG as binary data
data).
Audio → Transcribe
POST /v1/ai/transcribe. Turns the speech in an audio file or a video into
subtitle cues (cues), plus the same as srt and vtt and the full text.
Pass {{ $json.cues }} (or srt) to a template's subtitles parameter to burn
them into an MP4. Costs 1 AI credit per minute of audio.
- Input: a URL or a Binary File (MP3, M4A, WAV, Ogg, MP4, WebM;
up to 100 MB and 2 hours). - Options: Language (detected when empty), Style (Standard: 2 lines of
42 characters; Short: one line of 24, for vertical video), Max Characters
per Line, Max Lines per Cue, Start and Duration (only a window of the file),
Offset (moves the cues on your video's timeline), Include Word Timings.
Social Account → Get Many
GET /v1/social/accounts: the accounts connected in the app (connecting
needs the platforms' OAuth in a browser, so it happens in the app).
Social Post → Create / Get / Get Many / Cancel / Retry
POST /v1/social/posts and friends.
- Accounts: pick from the connected accounts (sandbox accounts and accounts
that need reconnecting are labelled). - Caption, and per-platform captions under Additional Fields.
- Media: Render a Template (same template picker and parameters as
Render; the render is charged when the post goes out; several pages become a
carousel, a PDF a LinkedIn document), An Earlier Render (arenderId,
e.g. from Render Template), Media URLs, or None (drafts). - Additional Fields: Scheduled At + Time Zone, Draft, Pages, Scale,
Quality, Platform Options (JSON, e.g.{"tiktok": {"privacyLevel": "SELF_ONLY"}}).
Every account is checked against its platform's rules before anything is
created; a refusal fails the node with every problem listed. Publishing is
asynchronous: use Get, or the trigger's social.post.* events, for each
account's permalink or error.
Social Analytics Report → Get Overview / Get Daily / Get Insights
GET /v1/social/analytics/overview, /daily and /insights: how the
workspace's posts are doing (impressions or views, reach, likes, comments,
shares, saves, clicks, engagement). From and To pick the days (the
last 28 days when empty; days are in the organization's analytics time zone);
Filters narrow it to some platforms or accounts. A metric is null when
the platforms in scope don't report it. Free.
- Get Overview: one item with the totals, the period before and the change
in percent. - Get Daily: one item per day (
day, the metrics,postsPublished,timezone), ready for a sheet or a chart. - Get Insights: one item with the top 5 posts, the best weekday and hour
to post, and each platform compared.
Workflow → Get / Get Many / Run
Workflows are made in the app (Workflows): they read rows from Google Sheets,
a CSV or XLSX file, Airtable, a Drive folder or an incoming webhook, render a
template per row and deliver each render. This node starts them and reads
their results.
- Workflow: pick from the list or paste an ID.
- Run (
POST /v1/workflows/{id}/run): starts a run now, drafts included.
Each row costs the usual render credits. Options: Max Rows (a test run),
Rows (JSON: the rows for a workflow whose source is an incoming webhook),
Timeout. - Wait for Completion (default on): polls
GET /v1/workflows/{id}/runs/{runId}until the run ends (Timeout, 600 s
by default; the run keeps going), then outputs the run with each row'sstatus,urls,deliveriesanderror. Afailedrun (no row went
through) fails the node;partialandcanceledruns are output. Off:
output the queued run at once. - Get / Get Many: the workflow with its steps, trigger, last run and
problems(what stops it from running).
Workflow Run → Get / Get Many / Cancel
GET /v1/workflows/{id}/runs/{runId} (with each row's result),GET /v1/workflows/{id}/runs (newest first) andPOST /v1/workflows/{id}/runs/{runId}/cancel (rows not started yet are
skipped; the row in progress finishes).
Errors
API errors fail the node with the API's message (for example Quota exceeded: requested 3, remaining 1 of 100); the error code (QUOTA_EXCEEDED,VALIDATION_ERROR, NOT_FOUND…) and detail are in the error's description,
and the HTTP status in its code. A 429 is retried twice after Retry-After.
With Settings → On Error → Continue, the item carries error instead.
Trigger
The JamFrame Trigger node uses the API's webhook subscriptions (REST
hooks):
- Activating the workflow calls
POST /v1/webhooks/subscriptionswith
n8n's webhook URL and the chosen events, and keeps the subscription ID and
its signing secret (shown only once) in the node's static data. - Each delivery's
X-Webhook-Signature(t=<unix>,v1=<HMAC-SHA256 of "t.<raw body>">) is checked against that secret on the raw request body,
with a 5-minute tolerance. A delivery that fails the check is answered401and doesn't start the workflow (turn Verify Signature off only to
debug). - Deactivating the workflow deletes the subscription. Changing the events or
the URL replaces it.
Each execution gets the event envelope: id, type, createdAt, data (a
render job for render.*, { post, target } for social.post.*, the template
summary for design.*, the run plus workflowName for workflow.run.*) anddeliveryId (the X-Webhook-Delivery header, the
same across retries: use it to deduplicate, since delivery is at-least-once).
A workspace can have at most 20 subscriptions.
Your n8n must be reachable from the internet. The API only delivers to
public addresses (no localhost, private or link-local hosts) and requireshttps:// in production. n8n's webhook URLs are http://localhost:5678/… by
default, so on a local n8n set WEBHOOK_URL to a public HTTPS address (for
example a tunnel such as cloudflared or ngrok) before activating, or
activation fails with url must not target a private host. n8n's test URL
(/webhook-test/…) and production URL (/webhook/…) differ; the node
re-subscribes when the URL changes.
Without the trigger node
If you can't use the node (an older n8n, or you want one endpoint for several
workflows):
Add n8n's built-in Webhook node (POST, Raw Body on), activate the
workflow and copy its production URL.In the app, open Webhooks, add a subscription with that URL and the
events, and copy the signing secret it shows once (or usePOST /v1/webhooks/subscriptionswith your API key).Verify the signature in a Code node before acting on the event:
const crypto = require('crypto'); const secret = $env.JAMFRAME_WEBHOOK_SECRET; // or paste it in a credential const item = $input.first(); // The raw body (works with n8n's filesystem and S3 binary modes too). const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); const header = item.json.headers['x-webhook-signature'] ?? ''; const parts = Object.fromEntries(header.split(',').map((p) => p.split('='))); const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(raw).digest(); const given = Buffer.from(parts.v1 ?? '', 'hex'); const ok = /^\d+$/.test(parts.t ?? '') && Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300 && given.length === expected.length && crypto.timingSafeEqual(given, expected); if (!ok) throw new Error('Bad signature'); return [{ json: JSON.parse(raw.toString('utf8')) }];(The Code node needs
NODE_FUNCTION_ALLOW_BUILTIN=cryptoon self-hosted
n8n.)
Example workflows
- Render and post: Schedule Trigger → Google Sheets (rows with
title,photo) → JamFrame Render Template (a carousel template,
parameters mapped automatically from the row, format JPEG) → JamFrame
Create Social Post (Media: An Earlier Render, Render ID{{$json.renderId}}, caption from the row). - Videos without waiting: Webhook → JamFrame Render Template (MP4, Run
as Job, Wait for Completion off) → respond with the job ID. A second
workflow starts on JamFrame Trigger (render.completed) and sends{{$json.data.result.content}}to Slack. - Post status: JamFrame Trigger (
social.post.failed) → Slack
message with{{$json.data.target.accountName}}and{{$json.data.target.error.message}}. - Product photos: Google Drive Trigger (new file in a folder) → Google
Drive Download → JamFrame Remove Background (Input: Binary File) →
JamFrame Render Template (the photo parameter{{$json.url}}) → JamFrame
Create Social Post. - Weekly report: Schedule Trigger (Mondays) → JamFrame Get Overview
(From:{{$today.minus({days: 7})}}) → Slack message with{{$json.totals.impressions}}and{{$json.change.engagement}}%. - Batch from the app: Schedule Trigger → JamFrame Run Workflow (a
workflow made in the app, Wait for Completion on) → Filter (rows withstatus=failed) → email the list.
Develop
npm install
npm run dev # n8n with this package loaded, rebuilding on changes (Docker or Podman since n8n 3)
npm run lint # n8n's community-node linter (n8n-node lint)
npm run build # tsc → dist/, plus the icons
npm test # build, then node:test unit tests (test/*.test.mjs), no n8n runtime or network
JAMFRAME_SMOKE_API_KEY=jf_live_… npm run test:smoke # the built node against a running API (1 credit)
n8n-node dev --external-n8n loads the package into an n8n you started
yourself with N8N_DEV_RELOAD=true.
The tests drive the built nodes with a fake n8n context whose HTTP helper
answers from a script: the render, render log, job polling, AI design (with
its job), background removal and transcription (URL and multipart uploads),
workflow runs, social post, analytics and pagination requests, error mapping,
the template and workflow pickers, the parameter mapper, and the trigger's
subscribe / verify / unsubscribe cycle. One test checks that every resource
and operation in the UI has a handler.
test:smoke (test/live.smoke.mjs) runs the built node against a real API:JAMFRAME_SMOKE_BASE_URL defaults to http://localhost:3100. It checks the
credential, the template picker, a one-page PNG render of a library template
(1 credit), the render log, workflows and analytics. WithJAMFRAME_SMOKE_AI=1 it also uploads that PNG to Remove Background (1 AI
credit).
Layout:
credentials/JamFrameApi.credentials.ts API key + base URL, Bearer auth, test request
nodes/JamFrame/ the action node: description files, methods (pickers, mapper, sizes, accounts), actions
nodes/JamFrameTrigger/ the trigger node
shared/brand.ts product name, default base URL, docs URL
shared/helpers.ts pure helpers (signature check, modifications, pagination, result shaping)
shared/transport.ts API calls, file uploads, error mapping, 429 retry, polling (render jobs, AI designs, workflow runs)
icons/ the JF mark (the same file for light and dark themes)
test/ unit tests, and the live smoke test
.github/workflows/ CI and the provenance publish workflow from n8n's template
Publishing (not done yet)
Nothing has been published. To publish and get the node verified (n8n's
requirements as of 2026-11-10):
- Decide the name and apply Renaming if it changes. Reserve
the npm name (n8n-nodes-jamframe, or@<org>/n8n-nodes-jamframeunder
an npm organization). - Create the public GitHub repository this package's URLs point at,
github.com/JamFrame-com/n8n-nodes-jamframe(therepositoryandhomepageinpackage.json, the codex.node.jsonfiles,documentationUrlin the
credential anddocsUrlinshared/brand.ts), and push this folder to it.
n8n checks that the npm package's repository URL, author and git link match
a public repository, and GitHub only runs workflows from a repository's
root.github/. - Check the icons in
icons/(SVG, light and dark variants) and the
author email inpackage.json. - npm: create the account (or organization), then add a Trusted
Publisher for the package (GitHub Actions, the repository, workflowpublish.yml), or store a granular token as theNPM_TOKENActions secret.
Since 1 May 2026 n8n accepts only packages published from GitHub Actions
with a provenance statement;.github/workflows/publish.ymldoes that on a
version tag. - Release:
npm run release(lint, build, version bump, changelog, tag,
push); the tag triggers the publish workflow. - Check:
npx @n8n/scan-community-package n8n-nodes-jamframeagainst
the published package. - Submit for verification at the n8n Creator Portal,
https://creators.n8n.io/nodes (review takes up to four weeks).
Requirements this package follows
Checked against n8n's documentation on 2026-11-10:
- Naming
n8n-nodes-…or@scope/n8n-nodes-…, then8n-community-node-package
keyword, and ann8nsection inpackage.jsonlistingdist/node and
credential files withn8nNodesApiVersion: 1andstrict: true
(submit community nodes,
the@n8n/node-clitemplate). - Built with the official tooling,
@n8n/node-cli0.55.6 (n8n-node build,lint,dev,release), from itsprogrammatic/exampletemplate
(n8n-node CLI). - Verification rules: MIT license, no runtime dependencies, no environment
variables or file access in the node code, English UI and docs, README,
publishing from GitHub Actions with provenance, programmatic style for the
trigger (declarative nodes can't be triggers)
(verification guidelines). resourceLocatorwith asearchListMethod, and aresourceMapperwith aresourceMapperMethod
(UI elements).- File layout
nodes/<Node>/<Node>.node.ts+.node.jsoncodex,credentials/<Name>.credentials.ts
(node file structure). - Manual install into
~/.n8n/nodes
(manual install). - n8n's linter (
@n8n/eslint-plugin-community-nodesvian8n-node lint)
passes with no errors or warnings. Among its rules: nosetTimeout(the
polling usessleepfromn8n-workflow), onlyn8n-workflowandnode:cryptoimported, errors thrown asNodeApiError/NodeOperationError,
literal credentialdocumentationUrl, codex categories from n8n's list, node
file names that match the node'sname, singular resource names. - File uploads (Remove Background, Transcribe) use the runtime's built-in
FormDataandBlob, not theform-datapackage (no dependencies allowed).
n8n'shttpRequesthands them to axios, which streams them asmultipart/form-data; checked with n8n-core 2.16 against an echo server.
Renaming
shared/brand.ts holds the display name, the default base URL, the API key
hint and the docs URL. n8n requires the rest to be literals, so a rename also
edits (all before the first publish; node and credential names are stored in
users' workflows):
package.json:name,description,keywords,homepage,repository,author, and then8n.nodes/n8n.credentialspaths if files are renamed.credentials/JamFrameApi.credentials.ts: the class name,name = 'jamFrameApi'(alsoCREDENTIAL_NAMEinshared/brand.tsand thecredentialsentry of both nodes),displayName,documentationUrl.nodes/JamFrame/JamFrame.node.tsandnodes/JamFrameTrigger/JamFrameTrigger.node.ts: the class names,name: 'jamFrame'/'jamFrameTrigger', the trigger'sdisplayName
(n8n's linter wants "Trigger" in a literal). The linter also wants each
node file named after itsnamewith a capital first letter (jamFrame→JamFrame.node.ts).- The
.node.jsoncodex files:node(<package>.<node name>) and the URLs. - The folder, file and icon names, and the paths in
test/.