PixelFireman Get an API key
API REFERENCE

PixelFireman API

A cheaper, drop-in image-generation API. Send a prompt, get back an image. Pay as you go with credits bought in your dashboard — no subscriptions, no free tier, credits never expire.

Getting an API key

  1. Sign up at pixelfireman.com/account.html.
  2. Buy a credit pack (see Credits & pricing).
  3. Copy your API key from the account dashboard. Keys look like pf_live_xxxxx….

Keep your key secret. Treat it like a password — anyone with it can spend your credits.

Authentication

Every request must include your API key. Two header forms are accepted — use either one:

Authorization: Bearer YOUR_API_KEY

or

x-api-key: YOUR_API_KEY

Requests without a valid key return 401.

Generate an image

POST/v1/images

Send a JSON body with a Content-Type: application/json header.

Request parameters

FieldTypeRequiredDefaultDescription
promptstringYes—What to generate.
modestringNo"auto"One of "auto", "generate", "draw". generate = realistic photo/image (fast diffusion model). draw = clean flat SVG vector art (logos/icons). auto = let the service pick the best engine.
sizestringNo"1024x1024"Output dimensions. Examples: "1024x1024" (square), "1024x1536" (portrait), "1536x1024" (landscape).

Response

FieldTypeDescription
enginestringWhich engine served the request.
costnumberCost in USD for this single image.
formatstring"url" or "svg". Tells you how to read the image field.
imagestringIf format is "url": an https URL to the PNG/JPG — fetch/download it. If format is "svg": the raw SVG markup string.
usageobject{ images, cost } — running totals for this key.

Example response (generate mode):

{
  "engine": "diffusion-fast",
  "cost": 0.02,
  "format": "url",
  "image": "https://pixelfireman.com/i/abc123.png",
  "usage": { "images": 42, "cost": 0.84 }
}

Example response (draw mode):

{
  "engine": "vector",
  "cost": 0.02,
  "format": "svg",
  "image": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\">…</svg>",
  "usage": { "images": 43, "cost": 0.86 }
}

Generate a video

POST/v1/videos

Generate a short (~5-second) video clip. Same Bearer auth as /v1/images. Send a JSON body with a Content-Type: application/json header.

Video is billed from a separate “video minutes” wallet — it does not spend image credits. See Video minutes & pricing.

Request parameters

FieldTypeRequiredDefaultDescription
promptstringYes—What to generate (a short ~5-second clip).
tierstringNo"economy"One of "economy", "standard", "premium". Higher tiers cost more minutes and look better.

Response

FieldTypeDescription
tierstringThe tier that served the request.
formatstringAlways "url" for video.
videostringAn https URL to the generated MP4 — fetch/download it.
minutesUsednumberVideo minutes spent on this clip.
usageobject{ minutesLeft } — the video-minutes wallet balance after this request.

Example response:

{
  "tier": "economy",
  "format": "url",
  "video": "https://pixelfireman.com/v/abc123.mp4",
  "minutesUsed": 30,
  "usage": { "minutesLeft": 470 }
}

A note on timing: premium clips can take up to ~4–5 minutes to generate; economy and standard are faster. The request stays open until the MP4 is ready. “Minutes” here are wallet credits, not the clip length — every clip is about 5 seconds long regardless of tier.

Code examples

Replace YOUR_API_KEY with your real key (pf_live_…) in each example.

cURL

# 1. Generate the image
curl -s https://pixelfireman.com/v1/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a red fox sitting in autumn leaves","mode":"generate","size":"1024x1024"}' \
  -o response.json

# 2. If format is "url", pull the URL out and download the file
IMG_URL=$(grep -o '"image":"[^"]*"' response.json | sed 's/"image":"//;s/"//')
curl -s "$IMG_URL" -o output.png
echo "Saved output.png"

Node.js (fetch — Node 18+)

import fs from "node:fs";

const API_KEY = "YOUR_API_KEY";

const res = await fetch("https://pixelfireman.com/v1/images", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "a red fox sitting in autumn leaves",
    mode: "generate",
    size: "1024x1024",
  }),
});

if (!res.ok) {
  const err = await res.json().catch(() => ({}));
  throw new Error(`HTTP ${res.status}: ${err.error || "request failed"}`);
}

const data = await res.json();
console.log("engine:", data.engine, "cost:", data.cost, "credits used:", data.usage.images);

if (data.format === "url") {
  // Download and save the PNG/JPG
  const img = await fetch(data.image);
  const buf = Buffer.from(await img.arrayBuffer());
  fs.writeFileSync("output.png", buf);
  console.log("Saved output.png");
} else {
  // SVG markup — save directly
  fs.writeFileSync("output.svg", data.image);
  console.log("Saved output.svg");
}

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"

res = requests.post(
    "https://pixelfireman.com/v1/images",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "a red fox sitting in autumn leaves",
        "mode": "generate",
        "size": "1024x1024",
    },
    timeout=120,
)

if not res.ok:
    raise SystemExit(f"HTTP {res.status_code}: {res.json().get('error', 'request failed')}")

data = res.json()
print("engine:", data["engine"], "cost:", data["cost"], "credits used:", data["usage"]["images"])

if data["format"] == "url":
    # Download and save the PNG/JPG
    img = requests.get(data["image"], timeout=120)
    with open("output.png", "wb") as f:
        f.write(img.content)
    print("Saved output.png")
else:
    # SVG markup — save directly
    with open("output.svg", "w", encoding="utf-8") as f:
        f.write(data["image"])
    print("Saved output.svg")

cURL — video

# 1. Generate the clip (premium can take ~4-5 min; keep the connection open)
curl -s --max-time 400 https://pixelfireman.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a red fox trotting through autumn leaves","tier":"economy"}' \
  -o video-response.json

# 2. Pull the MP4 URL out and download the file
VID_URL=$(grep -o '"video":"[^"]*"' video-response.json | sed 's/"video":"//;s/"//')
curl -s "$VID_URL" -o output.mp4
echo "Saved output.mp4"

Node.js (fetch — Node 18+) — video

import fs from "node:fs";

const API_KEY = "YOUR_API_KEY";

// Premium clips can take ~4-5 minutes — do not set a short client timeout.
const res = await fetch("https://pixelfireman.com/v1/videos", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "a red fox trotting through autumn leaves",
    tier: "economy",
  }),
});

if (!res.ok) {
  const err = await res.json().catch(() => ({}));
  throw new Error(`HTTP ${res.status}: ${err.error || "request failed"}`);
}

const data = await res.json();
console.log("tier:", data.tier, "minutes used:", data.minutesUsed, "minutes left:", data.usage.minutesLeft);

// Download and save the MP4
const vid = await fetch(data.video);
const buf = Buffer.from(await vid.arrayBuffer());
fs.writeFileSync("output.mp4", buf);
console.log("Saved output.mp4");

Handling the response

Always branch on format:

mode: "draw" typically returns svg; mode: "generate" typically returns url. With mode: "auto" always check format before using image.

Check your usage

GET/v1/usage

Send the same Authorization (or x-api-key) header. No body.

curl -s https://pixelfireman.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "name": "My App Key",
  "images": 142,
  "cost": 2.84,
  "lastUsed": "2026-10-01T18:22:04.000Z",
  "daily": { "2026-10-01": 12, "2026-09-30": 30 }
}
FieldTypeDescription
namestringLabel for this key.
imagesnumberTotal images generated with this key.
costnumberTotal USD cost across all images.
lastUsedstringISO timestamp of the last request.
dailyobjectImages generated per day (date → count).

Errors

Errors return the matching HTTP status plus a JSON body { "error": "..." }.

StatusMeaningWhat to do
400Bad requestA required field is missing (usually prompt) or tier is not one of economy/standard/premium. Fix the body.
401Invalid or missing API keyCheck the Authorization / x-api-key header and your key.
402Out of credits / minutesImage calls: out of credits. Video calls: not enough video minutes. Buy more in the dashboard.
451Blocked by content moderationThe prompt was rejected. No real public figures, no sexual or illegal content. Reword and retry.
500Server errorTransient — generation failed. Retry with backoff; contact support if it persists. Video minutes are not charged on a failed generation.

Example error body:

{ "error": "out of credits" }

Credits & pricing

PackCredits
$10150
$25400
$50800

Buy packs with PayPal in the account dashboard.

Video minutes & pricing

Video is billed from a separate “video minutes” wallet — it does not touch your image credits. 1 minute = $0.01. “Minutes” are wallet credits, not the length of the clip — every clip is about 5 seconds long.

Each ~5-second clip costs:

TierMinutesCost per clip
economy30$0.30
standard60$0.60
premium150$1.50

Buy video minutes with PayPal in the account dashboard. Minutes never expire.

PackMinutes
$5500
$202,000
$505,500
$10012,000

Integrating into your app / AI agent

This is a standard REST API with Bearer authentication, so it drops into any stack: