pixshot

n8n community node for the PixShot OG-image API (https://pixshot.dev)

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0

Documentation

n8n-nodes-pixshot

n8n community node for the PixShot OG-image API. Generate
Open Graph (social card) images from a title, subtitle and style parameters
directly inside an n8n workflow.

Status: not yet published to npm. The release workflow uses GitHub OIDC;
first publication and npm Trusted Publisher authorization are still required
(see Publishing).

What it does

The node exposes one operation, Generate OG Image, which calls:

POST https://api.pixshot.dev/v1/og-image

with a JSON body:

{
  "template": {
    "title": "Required title",
    "subtitle": "Optional subtitle",
    "logo_url": "https://example.com/logo.png",
    "background_color": "#1a1a2e",
    "text_color": "#ffffff",
    "font_size": 64
  }
}

On success the raw PNG bytes returned by the API are placed on the output item
as a binary property named data (file og-image.png, MIME image/png). The
item's JSON carries { "format": "png" } plus the plan from the
X-PixShot-Plan response header when available.

Server errors (invalid key, quota exceeded, etc.) are surfaced with the
server's error message.

Parameters

Parameter Type Required Constraints API key
Title string yes 1–500 characters title
Subtitle string no up to 500 characters subtitle
Logo URL string no valid http(s) URL logo_url
Background Color color no #RRGGBB background_color
Text Color color no #RRGGBB text_color
Font Size number no integer 16–128 (default 64) font_size

Credential setup

  1. Register self-service at https://pixshot.dev/docs.
    The API key is delivered by email.
  2. In n8n, create a PixShot API credential and paste the key into
    API Key. The node sends it as the x-api-key request header.

Installation (once published)

# From the n8n UI: Settings → Community Nodes → Install
n8n-nodes-pixshot

Or with npm inside your n8n installation:

npm install n8n-nodes-pixshot

Example workflow sketch

{
  "nodes": [
    {
      "parameters": {
        "operation": "generateOgImage",
        "title": "Shipping v2 of our API",
        "subtitle": "Faster, typed, and boring in a good way",
        "backgroundColor": "#1a1a2e",
        "textColor": "#ffffff",
        "fontSize": 64
      },
      "name": "PixShot",
      "type": "n8n-nodes-pixshot.pixShot",
      "typeVersion": 1,
      "position": [400, 300]
    }
  ]
}

The binary data output plugs straight into nodes such as Upload to S3,
Telegram (Send Photo) or HTTP Request (multipart).

Development

pnpm install --frozen-lockfile # install dev dependencies (no runtime dependencies)
pnpm test                     # run the test suite (vitest)
pnpm run lint                 # strict TypeScript typecheck (src + tests)
pnpm run build                # compile src/ → dist/

No API calls are made by the tests; the HTTP helper is mocked.

Publishing

The package publishes from .github/workflows/publish-n8n-node.yml using
npm Trusted Publishing. No permanent
npm token is stored in GitHub. The workflow uses GitHub-hosted runners, Node 24,
npm 11.21.2 and id-token: write.

One-time npm setup

The package must exist in npm before its package settings can authorize a
publisher. If npm view n8n-nodes-pixshot returns 404, a maintainer must perform
the initial publication from this directory after interactive npm login:

pnpm install --frozen-lockfile
pnpm run lint && pnpm test && pnpm run build
npm publish --access public

Do not publish placeholder contents or upload an npm token to GitHub for this
bootstrap. This consumes version 0.1.0; subsequent releases need a new version.

In npm → package Settings → Trusted publishing, authorize GitHub Actions with:

  • Organization or user: Urdlabs
  • Repository: pixshot
  • Workflow filename: publish-n8n-node.yml
  • Environment: leave blank (the job does not declare a GitHub Environment).

Configure the publisher near the next release: unused new configurations expire
after two days. After the first successful OIDC release, restrict publishing to
2FA and disallow traditional tokens in npm's Publishing access settings.

Subsequent releases

  1. Bump the package version and merge to main after validation.
  2. Dispatch Publish n8n-nodes-pixshot with dry_run: true (the default) to
    typecheck, test, build and inspect packaging without publishing.
  3. Dispatch from main with dry_run: false to publish via OIDC. Other branches
    cannot execute the publishing step. A dry run does not prove npm authorized
    the publisher; verify the published version with npm view after release.

Urdlabs/pixshot is private, so provenance stays disabled through
NPM_CONFIG_PROVENANCE=false. OIDC authentication still works for private
repositories. Enable the provenance input only after making the source public;
that visibility change is a separate business decision.

License

MIT

Discussion