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.

For AI agents, MCP in one line

Building an agent on Claude? PixelFireman ships as an MCP server, so a Claude Desktop or Claude Code agent can generate images and video as a native tool. Add this to your MCP config, drop in your key, and the agent gets three tools instantly:

{
  "mcpServers": {
    "pixelfireman": {
      "command": "npx",
      "args": ["-y", "pixelfireman-mcp"],
      "env": { "PF_API_KEY": "pf_live_xxx" }
    }
  }
}

Tool	What it does
generate_image	prompt → image URL (or SVG). Args: prompt, size, mode.
generate_video	prompt → short clip URL. Args: prompt, tier.
check_balance	returns remaining image credits and video minutes.

Example agent prompt: “Generate a wide, bright image of a modern kitchen renovation and give me the URL.”, the agent calls generate_image and returns the link. Machine-readable spec: openapi.json.

Copy setup for Claude / ChatGPT Download .md

Paste it into your AI assistant and it will know how to call PixelFireman.

---

• Base URL: https://pixelfireman.com
• A 1024×1024 image = 1 credit; credits scale with megapixels.
• Two modes: fast realistic images (generate) and clean flat SVG vector art (draw), or let the service pick (auto).
• Also generates short video clips, POST /v1/videos (billed from a separate video-minutes wallet, see Generate a video).

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

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

Request parameters

Field	Type	Required	Default	Description
prompt	string	Yes	,	What to generate.
mode	string	No	"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.
size	string	No	"1024x1024"	Output dimensions. Examples: "1024x1024" (square), "1024x1536" (portrait), "1536x1024" (landscape).

Response

Field	Type	Description
engine	string	Which engine served the request.
cost	number	Cost in USD for this single image.
format	string	"url" or "svg". Tells you how to read the image field.
image	string	If format is "url": an https URL to the PNG/JPG, fetch/download it. If format is "svg": the raw SVG markup string.
usage	object	{ 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

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

Field	Type	Required	Default	Description
prompt	string	Yes	,	What to generate (a short ~5-second clip).
tier	string	No	"economy"	One of "economy", "standard", "premium". Higher tiers cost more minutes and look better.

Response

Field	Type	Description
tier	string	The tier that served the request.
format	string	Always "url" for video.
video	string	An https URL to the generated MP4, fetch/download it.
minutesUsed	number	Video minutes spent on this clip.
usage	object	{ 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:

• format: "url", image is an https link to a PNG/JPG. Fetch it to download the bytes, or store the URL and serve it directly. Download it if you need a permanent copy; do not assume the URL lives forever.
• format: "svg", image is the raw SVG markup. Write it to a .svg file, inline it into HTML, or render it however you like. No second request needed.

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

Check your 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 }
}

Field	Type	Description
name	string	Label for this key.
images	number	Total images generated with this key.
cost	number	Total USD cost across all images.
lastUsed	string	ISO timestamp of the last request.
daily	object	Images generated per day (date → count).

Errors

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

Status	Meaning	What to do
400	Bad request	A required field is missing (usually prompt) or tier is not one of economy/standard/premium. Fix the body.
401	Invalid or missing API key	Check the Authorization / x-api-key header and your key.
402	Out of credits / minutes	Image calls: out of credits. Video calls: not enough video minutes. Buy more in the dashboard.
451	Blocked by content moderation	The prompt was rejected. No real public figures, no sexual or illegal content. Reword and retry.
500	Server error	Transient, 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

• Credits scale with size. A 1024×1024 image = 1 credit; a 1536×1536 ≈ 2 credits (fal bills per megapixel). The response returns creditsUsed.
• No free tier. Buy a credit pack to start.
• Credits never expire.

Pack	Images	Per 1,000
$10	1,400	~$7.14
$25	3,750	~$6.67
$50	8,000	~$6.25

Buy packs with PayPal in the account dashboard. That is about $0.0071 per image at the Pro pack.

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:

Tier	Minutes	Cost per clip
economy	30	$0.30
standard	60	$0.60
premium	150	$1.50

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

Pack	Minutes
$5	500
$20	2,000
$50	5,500
$100	12,000

Integrating into your app / AI agent

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

• Any HTTP client works, fetch, axios, requests, curl, Go net/http, PHP curl, and so on. One POST /v1/images with a JSON body and an Authorization: Bearer header is all you need.
• AI agents / tool-use / function-calling: expose a single tool, e.g. generate_image(prompt, mode, size), that performs the POST /v1/images call and returns format + image. The small, flat request/response shape maps cleanly to a function schema. Have the agent branch on format (url vs svg) when handling the result.
• Rate / cost control: poll GET /v1/usage to track spend, and handle 402 by prompting the user to top up. Handle 451 by surfacing the moderation message so the agent can reword the prompt and retry.