Pixfaro API & MCP

Every image model behind one endpoint: your agent asks for an image; Pixfaro holds the provider accounts, keys, retries and format differences, and bills one prepaid balance.

• Site pixfaro.com
• API https://api.pixfaro.com
• MCP https://mcp.pixfaro.com/mcp
• Agents llms.txt

REST API REST

Base URL https://api.pixfaro.com. JSON everywhere. Errors use one envelope:

{ "error": { "code": "insufficient_balance", "message": "…", "request_id": "rq_a1c4f0" } }

Every response carries an x-request-id header — include it when you contact support. Money is always a USD decimal string ("0.080", never a float). Times are ISO 8601 UTC.

Authentication

Keys are created on the dashboard. Scopes: generate (default — image endpoints only) and full (adds balance, billing, logos, and brand-kit management).

New accounts must verify their email before generating — unverified calls return 403 email_unverified. The $1 welcome credit lands on verification (instantly for Google/GitHub signups).

POST /v1/images/generations

Generate an image. Sync — the response is the finished image.

{
  "model": "nano-banana-2",
  "prompt": "a lighthouse at night, minimal flat style",
  "aspect_ratio": "16:9",
  "resolution": "1K",
  "overlay": "default"
}

n > 1 and response_format other than "url" are not supported yet — one image per request, delivered as a hosted URL (your agent's context never carries base64).

200:

{
  "id": "img_8f2a…", "url": "https://api.pixfaro.com/i/…", "model": "nano-banana-2",
  "resolution": "1K", "latency_ms": 10400, "cost": "0.080", "balance_after": "12.32",
  "overlay_applied": false, "request_id": "rq_a1c4f0"
}

Errors: 402 insufficient_balance (body includes balance, needed, topup_url), 400 invalid_model / invalid_prompt / invalid_request, 403 email_unverified, 409 model_disabled, 429 rate_limited, 502 provider_failed — no charge, and the body says so explicitly: "charged": false.

Overlay object

Brands a corner of the image with your handle or logo. Exactly one of text (≤ 64 chars) or logo_id (a logo_… from POST /v1/logos):

{ "overlay": { "text": "@yourbrand", "position": "bottom-right", "opacity": 0.9 } }

Optional: position (default bottom-right), opacity (0.2–1.0; text defaults to 0.9, logos to 1.0), logo_style (sticker — default — | shadow | outline | none), size, margin, and for text font / weight / color ("auto" picks ink or paper per corner brightness). Save your defaults once via PUT /v1/brand-kit, then "overlay": "default" everywhere. A bad overlay fails the request before generation — you are not charged.

POST /v1/images/edits

Edit a previous generation with a natural-language instruction. Same response shape as generations.

{ "model": "nano-banana-2", "image": "img_8f2a…", "instruction": "make the sky darker" }

• image takes an img_… id from a previous generation (URLs are not accepted).
• instruction: 1–4000 chars — what to change; everything else stays put.
• Omitted aspect_ratio keeps the source image's shape (generations default to 1:1).
• Omitted resolution inherits — and bills at — the source image's tier.

GET /v1/models

Public, no auth. Cached ~5 min.

[{ "id": "nano-banana-2", "name": "Nano Banana 2",
   "best_for": "general-purpose images: blog art, social posts, mockups",
   "p50_ms": 10700, "p95_ms": 13600, "price": "0.080",
   "prices": { "1K": "0.080", "2K": "0.121", "4K": "0.181" },
   "mode": "sync", "enabled": true }]

price is the 1K figure; prices maps every supported resolution tier to its retail price. enabled: false marks models that are coming soon (calling one returns 409 model_disabled).

POST /v1/renders

Typeset a card from a template instead of generating one — flat $0.02, ~2s, sharp type. Full reference: Card templates.

curl https://api.pixfaro.com/v1/renders -H "Authorization: Bearer pf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"template":"quote-card","slots":{"quote":"Ship it.","handle":"@you"},"style":"auto"}'

A render is a generation: it returns an img_…, lands in your history, and is debited and refunded by the same rules.

GET /v1/templates

Public, no auth — the card catalog with slots, style axes and price. See Card templates.

GET /v1/balance

Requires scope full (a default generate key gets 403 insufficient_scope).

{ "balance": "12.32" }

Account endpoints (scope full)

Top-ups, keys, and usage are also on the dashboard.

POST /v1/abuse-reports

Public, no auth — report a generated image that violates our acceptable use policy: { "image_url", "reason", "details"?, "reporter_email"? } — image_url must be a Pixfaro-served image link (…/i/…); reason is one of csam, nonconsensual, violence_hate, infringement, other.

Rate limits

Fair-use limits apply on auth and abuse-prone endpoints (429 rate_limited). There is no fixed per-key request cap today; sustained high volume is welcome — talk to us if you're planning a big batch.

Versioning

Path-versioned (/v1/). Additive changes (new optional fields) don't bump the version; breaking changes go to /v2/ with 6 months of /v1/ support. The x-pixfaro-deprecation header announces sunsets ahead of time.

Card templates CARDS

Not every image needs a model. A card is typeset, not generated: you send text, we render it in a real browser and hand back a hosted PNG. Flat $0.02, about two seconds, and the type comes out sharp — which is the one thing image models still get wrong.

Same key, same balance, same MCP as everything else. A render returns an img_… at /i/…, shows up in your history, and can be downloaded, edited or overlaid like any other image.

curl https://api.pixfaro.com/v1/renders \
  -H "Authorization: Bearer pf_live_…" -H "Content-Type: application/json" \
  -d '{"template":"quote-card",
       "slots":{"quote":"Stop mistaking silence for nobody'\''s home.","handle":"@dashaworks"},
       "style":"auto"}'

{ "id": "img_4e1807777fc895e5642a",
  "url": "https://api.pixfaro.com/i/usr_…/img_….png",
  "kind": "render", "template": "quote-card", "size": "16:9",
  "style": { "palette": "charcoal", "font": "schibsted", "layout": "bold-left", "shadow": true },
  "cost": "0.020", "balance_after": "12.30", "latency_ms": 1412 }

GET /v1/templates

Public, no auth. Every template with its slots, style axes and exact price — enough to build a form from, which is what the dashboard does.

{ "templates": [
  { "id": "quote-card", "name": "Quote card", "tier": "simple", "price": "0.020",
    "best_for": "one line worth quoting — hooks, testimonials, pull quotes",
    "sizes": ["16:9", "1:1", "4:5", "og"],
    "slots": [ { "name": "quote", "type": "text", "required": true, "max": 280, "hint": "the line itself" } ],
    "styles": { "palettes": ["paper", "charcoal", …], "fonts": ["schibsted", …], "layouts": ["bold-left", …], "shadow": true } } ] }

POST /v1/renders

Scope generate is enough — a render is a generation.

Slots

Text slots take a string and are rejected (never truncated) past their max, so you never pay for a card that quietly lost its last sentence. Image slots take only Pixfaro-hosted references:

Arbitrary URLs are refused: the renderer is a real browser, and a fetchable slot would make every card a probe into whatever that browser can reach. "default" also works on the name and handle text slots.

Style

"auto" picks a random combination and avoids the one you used last on this template — two cards in a row that differ only in wording read as a bug, not as a series. "brand" paints your saved colours (identity.palette). An object pins whichever axes you name and defaults the rest:

{ "style": { "palette": "charcoal", "font": "instrument", "layout": "block", "shadow": true } }

The chosen combination comes back in the response, so a card you like can be re-rendered exactly.

Errors

POST /v1/assets

Scope full. PNG or JPEG, ≤ 5 MB, ≤ 4096 px/side, 100 live per account. Raw binary with ?kind=avatar, or JSON:

curl https://api.pixfaro.com/v1/assets \
  -H "Authorization: Bearer pf_live_…" -H "Content-Type: application/json" \
  -d '{"kind":"avatar","data":"data:image/png;base64,…"}'

→ { "id": "ast_…", "kind": "avatar", "width": 512, "height": 512 }

GET /v1/assets?kind=avatar lists yours; DELETE /v1/assets/:id removes one. Assets are private — they are never served at a public URL; the renderer reads them server-side and inlines them into the card.

Uploading a photo of a person means you have the right to use it. Personas are self-likeness only, and attributing words to someone who did not say them is impersonation whatever the styling — see the acceptable use policy.

Brand identity

PUT /v1/brand-kit/identity (scope full) is what "default" resolves to:

{ "name": "Dasha", "handle": "@dashaworks", "avatar_asset_id": "ast_…",
  "palette": { "bg": "#101014", "ink": "#fdfdfb", "accent": "#b4e33d" } }

It sits beside the overlay brand kit (/v1/brand-kit) and is cleared separately.

Template catalog

More arrive with composition — an image slot you can fill with a generation in the same request.

Fonts

Cards are set in self-hosted SIL OFL 1.1 faces — no font CDN in the render path, so a card is deterministic and its typography does not depend on a third party being up. The licence text ships beside every family we serve.

Cyrillic text set in a Latin-only face is switched to the closest Cyrillic-capable face of the same class (Manrope, Playfair Display or IBM Plex Mono), rather than falling through to a system font mid-headline.

MCP server MCP

One MCP connection gives your agent every major image model. Two ways in:

Source: github.com/pixfaro/mcp — the client is intentionally small enough to read before you hand it a key.

Setup — no terminal needed

The remote server is the easiest path on every desktop app: paste one URL, sign in with your Pixfaro account in the browser window that opens, done. No API key ends up in any config file.

Claude (claude.ai, Claude Desktop — any plan):

1. Settings → Connectors → Add custom connector
2. URL: https://mcp.pixfaro.com/mcp → Add → sign in when prompted. On Team/Enterprise an org Owner adds it once for everyone (Organization settings → Connectors → Custom → Web).

Cursor — one click:

Add to Cursor →

or by hand: Cursor Settings → MCP → Add new MCP server, type URL, address https://mcp.pixfaro.com/mcp — Cursor runs the OAuth flow itself.

ChatGPT (Pro / Plus / Business / Edu):

1. Settings → toggle Developer mode on (since the July 2026 rename the connector list lives under Plugins; before that it was Connectors → Advanced)
2. Add a custom connector: name pixfaro, URL https://mcp.pixfaro.com/mcp, transport streamable HTTP, authentication OAuth → sign in.

Setup — command line & config files

Claude Code:

claude mcp add pixfaro -e PIXFARO_KEY=pf_live_… -- npx -y @pixfaro/mcp

Windsurf or any stdio client (config file; key from the dashboard):

{
  "mcpServers": {
    "pixfaro": {
      "command": "npx",
      "args": ["-y", "@pixfaro/mcp"],
      "env": { "PIXFARO_KEY": "pf_live_…" }
    }
  }
}

Clients that speak streamable HTTP can also use the remote form in the same file — no key, OAuth on first use:

{ "mcpServers": { "pixfaro": { "url": "https://mcp.pixfaro.com/mcp" } } }

Tools

Replies are agent-readable text carrying a hosted URL — never base64, so your agent's context stays small. When the balance runs low, replies append a top-up warning.

Environment (stdio)

CLI

The same repo ships the pixfaro CLI for scripts, CI, and pipelines — the literal one-command time-to-first-image:

export PIXFARO_KEY=pf_live_…
npx pixfaro gen "a lighthouse at night, minimal flat style" -a 16:9 -o cover.png
npx pixfaro edit img_8f2a… "make the sky darker" -o v2.png
npx pixfaro models
npx pixfaro balance

-o downloads the image; without it the CLI prints the hosted URL. A failed download never swallows the URL you already paid for.