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:

| Field | Value | |---|---| | API Key | An rfa_… key from Dashboard → API Keys | | Base URL | https://api.runfra.com (default — change only for non-production deployments) |

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.

| Field | Notes | |---|---| | Prompt | 1–2000 chars | | Batch Size | 1–100. Your account tier may cap the maximum batch size. | | Model | SDXL · FLUX Schnell · RunFra Pro (flux-dev) | | Width / Height | 512–1024 px | | Negative Prompt | (Additional Options) ignored for FLUX Schnell and RunFra Pro | | Quality Mode | strict (default) · soft · off | | Polling Timeout | seconds; default 300 — see below | | Notify On Complete | sends an email on terminal state (signed-in users with verified email) |

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.

| Field | Notes | |---|---| | Reference Image URL | Public HTTPS URL. PNG/JPEG/WebP, ≤10 MB, longest side ≤1024 px. SSRF-guarded server-side fetch. | | Scene Prompt | 1–2000 chars. The reference image dictates composition; this prompt drives style and surroundings. | | Output Width / Height | 384–768, multiples of 64. width × height ≤ 768×768. Default 512×512. | | Strength | (Additional Options) 0.4–0.9, default 0.6. Lower keeps the reference visible; higher re-imagines the frame. | | Crop Anchor | (Additional Options) center (default) or any of top/bottom/left/right/top-left/etc. Used when the reference and output aspect ratios differ. |

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.

| Field | Notes | |---|---| | Items | Add one row per prompt (each can override seed and negative prompt) | | Model / Width / Height / Quality Mode | Apply to every item | | Polling Timeout, Notify | (Additional Options) — same as single mode |

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:

| Model | ≤ 512 px | ≤ 768 px | > 768 px (1024×1024) | |---|---|---|---| | SDXL | 1 cr | 2 cr | 3 cr | | FLUX Schnell | 2 cr | 3 cr | 4 cr | | RunFra Pro (flux-dev) | 5 cr | 9 cr | 14 cr |

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