n8n-nodes-runfra

Community node for Runfra — async batch image generation
for high-volume creative and ecommerce automation. Generate from a prompt,
a list of prompts, or a product image URL + scene prompt, and receive final
image URLs in one workflow step. Models: SDXL, FLUX Schnell, RunFra Pro
(flux-dev).

v0.2 supports

• Generate Image — single prompt, batched candidates, top-pick selection.
• Generate Multiple Images — one image per prompt in one Runfra job.
• Generate Product Scene — image-to-image from a public HTTPS image URL plus a scene prompt.

Upscale, mockup, and Etsy fulfillment are not in this node yet. Those
workflows still use dashboard / JWT-only endpoints and have separate billing
semantics — they belong in the dashboard for now.

Install

In a self-hosted n8n instance:

1. Settings → Community Nodes → Install
2. Enter n8n-nodes-runfra
3. Confirm and reload n8n

Or install manually:

cd ~/.n8n
npm install n8n-nodes-runfra

Adding the node to a workflow

After install, the Runfra node is available in two places:

• Command Bar (Ctrl/Cmd + K → search "Runfra" → "Add Runfra")
• + Add Node panel — the standard node-creator search. Some n8n versions hide
  unverified community nodes here by default; if so, use the Command Bar.

Credentials

Create credentials of type Runfra API:

The API key is shown once at creation — save it immediately.

Operations

Generate Image (Single Prompt)

One scene, multiple candidates. Returns the Top Pick + every accepted URL.

Output (single item):

{
  "jobId": "a1b2c3d4-…",
  "status": "succeeded",
  "inputMode": "single",
  "bestResultUrl": "https://storage…/best.png",
  "resultUrls": ["…/0.png", "…/1.png"],
  "seeds": [2847391024, 1093847562, 7391820475, 4820193847],
  "acceptedCount": 3,
  "qualityScore": 0.87,
  "qualityPassed": true,
  "isBestEffort": false,
  "executionTimeMs": 13200
}

Generate Product Scene (From Reference Image)

Image-to-image: take a public image URL and a scene prompt, return one
restyled image. This operation currently submits SDXL img2img jobs;
output is capped at 768×768 px.

The node performs two backend calls in sequence:

1. POST /v1/uploads/input-image-by-url — server-side fetch, returns input_storage_key.
2. POST /v1/jobs with pipeline_mode=img2img and the storage key — then polls for the result.

Both calls use the same X-API-Key. The fetched image is owned by the API
key's user account and stored privately for 24 hours.

Output (single item):

{
  "jobId": "a1b2c3d4-…",
  "status": "succeeded",
  "inputMode": "single",
  "bestResultUrl": "https://storage…/best.png",
  "resultUrls": ["…/0.png"],
  "seeds": [2847391024],
  "acceptedCount": 1,
  "qualityScore": 0.84,
  "qualityPassed": true,
  "isBestEffort": false,
  "executionTimeMs": 18400
}

Generate Multiple Images (Multi Prompt)

One image per prompt, all in a single Runfra job.

Output (single item):

{
  "jobId": "a1b2c3d4-…",
  "status": "succeeded",
  "inputMode": "multi",
  "seeds": [42, 7291, 9012],
  "acceptedCount": 2,
  "qualityScore": 0.84,
  "items": [
    { "promptIndex": 0, "prompt": "a fox in a snowy forest", "status": "succeeded", "resultUrl": "…/0.png", "seed": 42, "errorMessage": null },
    { "promptIndex": 1, "prompt": "a whale diving underwater", "status": "succeeded", "resultUrl": "…/1.png", "seed": 7291, "errorMessage": null },
    { "promptIndex": 2, "prompt": "a green parrot on a branch", "status": "failed",  "resultUrl": null,        "seed": 9012, "errorMessage": "Quality gate: no passing candidates after 3 attempts" }
  ],
  "executionTimeMs": 28500
}

Use n8n's Split Out node to fan items[] into one workflow item per generated image.

Polling and timeouts

The node polls GET /v1/jobs/{id}/result every 3 seconds. Typical generation
is 10–30 seconds per task; large multi-prompt jobs can run longer.

If polling exceeds Polling Timeout seconds (default 300), the node does
not throw. It returns:

{ "jobId": "…", "status": "running", "timeoutExceeded": true, "seeds": […] }

Chain a second Runfra node (or a plain HTTP Request to
GET https://api.runfra.com/v1/jobs/{jobId}/result) to keep polling. This
keeps long-running jobs out of n8n execution-timeout territory without
losing the job ID.

Pricing reference

Runfra uses prepaid credits shared across Dashboard, API, n8n, and MCP. This
node has no separate pricing.

Total cost = credits_per_image × effective_batch:

Single mode: effective_batch = batch_size. Multi mode: effective_batch = items.length.

Cost is frozen at submission. Platform failures and no-result jobs are
refunded automatically. Best-effort delivery (isBestEffort: true) does
not refund — the image is delivered even though no candidate cleared the
quality gate.

What this node does NOT do

• No upscale, mockup, or Etsy fulfillment yet. Those workflows still
  use dashboard / JWT-only endpoints and have separate billing semantics.
• No webhooks. The node polls; it does not register a callback. For
  fire-and-forget patterns, use a 30-second timeout, store the jobId,
  and resume polling later.

Develop

cd packages/n8n-nodes-runfra
npm install
npm run build       # compiles TS and copies the icon
npm run lint

To test in a local n8n: npm pack to create a tarball, then in your n8n
install directory npm install /absolute/path/to/n8n-nodes-runfra-*.tgz
and restart n8n. The glob avoids stale references when the version bumps.

License

MIT