PixelAPI Documentation

Complete API reference for AI product photography and image editing. Remove backgrounds, generate scenes, upscale, and more.

Quickstart

Remove your first product background in 3 steps:

1. Sign in at pixelapi.dev/app with Google. You get 10 free credits instantly.
2. Copy your API key from the dashboard.
3. Remove a background:

curl -X POST https://api.pixelapi.dev/v1/image/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

This returns a generation_id. Poll for the result:

curl https://api.pixelapi.dev/v1/image/GENERATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"

When status is "completed", the output_url contains your transparent PNG.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the dashboard after signing in with Google.

Rate Limits & Plans

Credit Costs

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Polling for Results

All image processing is asynchronous. Every endpoint returns a generation_id immediately. Poll GET /v1/image/{id} until done:

1. Submit a job → get generation_id
2. Poll GET /v1/image/{id} every 2–3 seconds
3. Status progresses: queued → processing → completed

Typical completion times:

• Background removal: 2–3 seconds
• Background replace: 5–10 seconds
• Image generation: 3–5 seconds
• Image generation: 8–13 seconds
• Upscaling: 10–30 seconds
• Face restoration: 3–5 seconds
• Object removal: 5–15 seconds

✂️ Remove Background NEW

Remove the background from an image and return a transparent PNG. Works great with product photos, portraits, objects, and complex edges.

Request — File Upload

Content-Type: multipart/form-data

Request — URL

Content-Type: application/json

*Provide either image (file upload) or image_url (JSON), not both.

Response

{
  "generation_id": "bg-rm-a1b2c3d4-...",
  "status": "queued",
  "operation": "remove-background",
  "credits_used": 4.0
}

cURL Example — File Upload

curl -X POST https://api.pixelapi.dev/v1/image/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

cURL Example — URL

curl -X POST https://api.pixelapi.dev/v1/image/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{"image_url": "https://example.com/product.jpg"}'

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")

# From local file
result = client.remove_background("product.jpg")
print(result.url)  # Transparent PNG URL

# From URL
result = client.remove_background(image_url="https://example.com/product.jpg")
print(result.url)

🎨 Replace Background NEW

Remove the background from a product image and replace it with an AI-generated scene. Describe the background you want with a text prompt.

Request — File Upload

Content-Type: multipart/form-data

Request — JSON with URL

Content-Type: application/json

Response

{
  "generation_id": "bg-rp-e5f6g7h8-...",
  "status": "queued",
  "operation": "replace-background",
  "credits_used": 8.0
}

cURL Example

curl -X POST https://api.pixelapi.dev/v1/image/replace-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]" \
  -F "prompt=product on marble countertop, soft natural window light, minimal scandinavian kitchen"

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")

result = client.replace_background(
    "product.jpg",
    prompt="product on marble countertop, soft natural window light, minimal"
)
print(result.url)  # Product composited onto AI scene

👤 Restore Face NEW

Enhance and restore faces in photos using our face-restore model. Fix blurry portraits, enhance low-res headshots, and improve team photos.

Request

Content-Type: multipart/form-data

Or JSON with image_url (string).

Response

{
  "generation_id": "face-i9j0k1l2-...",
  "status": "queued",
  "operation": "restore-face",
  "credits_used": 5.0
}

cURL Example

curl -X POST https://api.pixelapi.dev/v1/image/restore-face \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")
result = client.restore_face("blurry-portrait.jpg")
print(result.url)  # Enhanced image

🧹 Remove Object NEW

Remove unwanted objects from images using AI inpainting. Provide a mask image or a text description of what to remove.

Request

Content-Type: multipart/form-data

Provide either mask or prompt (or both for best results).

Response

{
  "generation_id": "obj-rm-m3n4o5p6-...",
  "status": "queued",
  "operation": "remove-object",
  "credits_used": 8.0
}

cURL Example — With Mask

curl -X POST https://api.pixelapi.dev/v1/image/remove-object \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]" \
  -F "[email protected]"

cURL Example — With Prompt

curl -X POST https://api.pixelapi.dev/v1/image/remove-object \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]" \
  -F "prompt=remove the watermark in the bottom right corner"

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")

# With mask
result = client.remove_object("photo.jpg", mask="mask.png")

# With prompt
result = client.remove_object("photo.jpg", prompt="remove the shadow on the left")

print(result.url)  # Cleaned image

🖼️ Generate Image

Generate an image from a text prompt using fast text-to-image or our text-to-image model.

Request Body

Content-Type: application/json

Response

{
  "generation_id": "a1b2c3d4-...",
  "status": "queued",
  "model": "flux-schnell",
  "credits_used": 5.0
}

cURL Example

curl -X POST https://api.pixelapi.dev/v1/image/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "model": "flux-schnell",
    "prompt": "Professional product photo of wireless earbuds, studio lighting, white background",
    "width": 1024,
    "height": 1024
  }'

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")
result = client.image.generate(
    prompt="Professional product photo of wireless earbuds, studio lighting",
    model="flux-schnell",
    width=1024,
    height=1024
)
print(result.url)

🔍 Upscale Image

Upscale an image to 4x resolution using our upscaling model. Great for making low-res product images print-ready.

Request

Content-Type: multipart/form-data or application/json

Response

{
  "generation_id": "up-q7r8s9t0-...",
  "status": "queued",
  "operation": "upscale",
  "credits_used": 20.0
}

cURL Example

curl -X POST https://api.pixelapi.dev/v1/image/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

Python SDK

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")
result = client.upscale("low-res-product.jpg")
print(result.url)  # 4x upscaled image

📋 Get Job Status

Poll this endpoint until status is completed, failed, or blocked. Works for all job types (background removal, generation, upscaling, etc.).

Response (completed)

{
  "id": "bg-rm-a1b2c3d4-...",
  "status": "completed",
  "output_url": "https://api.pixelapi.dev/outputs/images/2026/02/19/abc123.png",
  "operation": "remove-background",
  "credits_used": 4.0,
  "created_at": "2026-02-19T08:00:00Z"
}

Status Values

📦 List Models

Returns all available models and operations with their pricing and capabilities.

Available Models & Operations

🎵 Generate Audio NEW

Generate music, sound effects, and audio clips from text descriptions using Meta's our audio model model. Returns a WAV audio file URL.

Request

Content-Type: application/json

Credit Costs

• ≤15 seconds: 5 credits ($0.005)
• 16–30 seconds: 10 credits ($0.010)

Response

{
  "generation_id": "a1b2c3d4-...",
  "status": "queued",
  "model": "musicgen-small",
  "duration": 15,
  "credits_used": 8.0,
  "estimated_seconds": 30
}

Poll GET /v1/image/{generation_id} until status is "completed". The output_url will contain a WAV file.

cURL Example

curl -X POST https://api.pixelapi.dev/v1/audio/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "prompt": "upbeat Indian flute melody with tabla beats",
    "duration": 10
  }'

Python Example

import requests, time

API_KEY = "pk_live_your_key"
headers = {"Authorization": f"Bearer {API_KEY}", "User-Agent": "MyApp/1.0"}

# Generate audio
resp = requests.post("https://api.pixelapi.dev/v1/audio/generate",
    headers=headers,
    json={"prompt": "calm lofi hip hop beat with vinyl crackle", "duration": 15}
)
gen_id = resp.json()["generation_id"]

# Poll for result
while True:
    result = requests.get(f"https://api.pixelapi.dev/v1/image/{gen_id}", headers=headers).json()
    if result["status"] == "completed":
        print(f"Audio URL: {result['output_url']}")
        break
    time.sleep(3)

JavaScript Example

const resp = await fetch('https://api.pixelapi.dev/v1/audio/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'User-Agent': 'MyApp/1.0'
  },
  body: JSON.stringify({
    prompt: 'epic orchestral trailer music with drums',
    duration: 20
  })
});
const { generation_id } = await resp.json();

// Poll for result
let result;
do {
  await new Promise(r => setTimeout(r, 3000));
  result = await fetch(`https://api.pixelapi.dev/v1/image/${generation_id}`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }).then(r => r.json());
} while (result.status !== 'completed');

console.log('Audio URL:', result.output_url);

Example Prompts

• "upbeat Indian flute melody with tabla beats" — Bollywood-style background music
• "calm lofi hip hop beat with vinyl crackle and soft piano" — Study/focus music
• "epic orchestral trailer music with cinematic drums" — Video intros
• "ambient electronic music with soft pads and reverb" — Background ambience
• "acoustic guitar strumming, warm and cheerful" — Podcast/vlog intros
• "retro 8-bit video game soundtrack, fast tempo" — Game SFX

🎙️ Text-to-Speech NEW

Convert text to natural-sounding speech in 23 languages. Supports emotion tags like [laugh], [sigh], and zero-shot voice cloning from a 10-second reference audio clip.

Models

Parameters

cURL Example

curl -X POST https://api.pixelapi.dev/v1/tts/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "text=Hello, welcome to PixelAPI!" \
  -F "model=chatterbox-turbo" \
  -F "language=en"

Python Example

import requests, time

# Generate speech
resp = requests.post("https://api.pixelapi.dev/v1/tts/generate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    data={
        "text": "Hello! [laugh] This is amazing.",
        "model": "chatterbox-turbo",
        "language": "en"
    })
job = resp.json()
print(f"Job ID: {job['id']}, Credits: {job['credits_used']}")

# Poll for result
while True:
    status = requests.get(
        f"https://api.pixelapi.dev/v1/tts/status/{job['id']}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}).json()
    if status["status"] == "completed":
        print(f"Audio URL: {status['output_url']}")
        break
    elif status["status"] == "failed":
        print(f"Error: {status.get('error')}")
        break
    time.sleep(3)

JavaScript Example

const formData = new FormData();
formData.append('text', 'Hello! [laugh] This sounds great.');
formData.append('model', 'chatterbox-turbo');
formData.append('language', 'en');

const resp = await fetch('https://api.pixelapi.dev/v1/tts/generate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: formData
});
const job = await resp.json();

// Poll for result
const poll = setInterval(async () => {
  const s = await fetch(`https://api.pixelapi.dev/v1/tts/status/${job.id}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' }}).then(r => r.json());
  if (s.status === 'completed') {
    clearInterval(poll);
    console.log('Audio URL:', s.output_url);
  }
}, 3000);

Voice Cloning Example

# Clone a voice from a 10-second reference clip
curl -X POST https://api.pixelapi.dev/v1/tts/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "text=This is my cloned voice speaking." \
  -F "model=chatterbox-multilingual" \
  -F "language=en" \
  -F "voice_ref=@reference_voice.wav"

Supported Languages

GET /v1/tts/languages

Returns the full list of supported languages, models, emotion tags, and voice cloning details.

🧵 Pattern Generation NEW

Generate seamless, print-ready textile patterns. 8 styles. PatternedAI offers GUI-only at $0.015–0.045/image — we offer a self-serve API at $0.008–0.015/pattern.

Endpoints

Request

{
  "prompt": "small ditsy flowers, pastel rose pink",
  "style": "floral",
  "resolution": "512",
  "colors": "rose pink and ivory"  // optional
}

Response

{
  "generation_id": "uuid",
  "status": "pending",
  "model": "pattern-diffusion",
  "resolution": "512x512",
  "credits_charged": 8.0,
  "poll_url": "/v1/pattern/{id}"
}

Available Styles

{ "source_url": "https://...", "hue_shift": 90, "saturation_scale": 1.0 }

{ "source_url": "https://...", "target_size": 2048 }

Returns all available styles with descriptions and pricing.

Pricing

curl example

curl -X POST https://api.pixelapi.dev/v1/pattern/generate   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"prompt": "bold ikat diamonds, navy and gold", "style": "ikat", "resolution": "1024"}'

🎮 Game Assets NEW

Generate game-ready sprites, tiles, icons and UI elements. 7 art styles. Pixel-art and icon styles automatically produce transparent PNG sprites — ready to drop directly into Unity, Godot, or any game engine. 4x cheaper than Scenario.com ($0.005 vs $0.02+ per image).

Art Styles

Parameters

cURL Example

curl -X POST https://api.pixelapi.dev/v1/game-assets/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "knight warrior with sword and shield, facing right", "style": "pixel-art"}'

Python Example

import requests, time

resp = requests.post("https://api.pixelapi.dev/v1/game-assets/generate",
    headers={"Authorization": "Bearer YOUR_KEY"},
    json={"prompt": "wooden treasure chest with gold coins", "style": "icon"})

job = resp.json()

while True:
    s = requests.get(f"https://api.pixelapi.dev/v1/game-assets/{job['generation_id']}",
        headers={"Authorization": "Bearer YOUR_KEY"}).json()
    if s["status"] == "completed":
        print(f"Asset: {s['output_url']}")
        break
    time.sleep(3)

List All Styles

GET /v1/game-assets/styles

🎬 Generate Video NEW

Generate video clips from text prompts using WAN 2.1 T2V (14B FP8). Returns an MP4 video URL. Videos are generated at 16fps.

Request

Content-Type: application/json

Credit Costs

• T2V 480p: 50 credits ($0.050)
• T2V 720p: 100 credits ($0.100)

Response

{
  "generation_id": "a1b2c3d4-...",
  "status": "queued",
  "model": "seedance-1.5",
  "credits_used": 50.0,
  "estimated_seconds": 60
}

Poll GET /v1/video/{generation_id} until status is "completed". The output_url will contain an MP4 file.

Get Video Status

{
  "generation_id": "a1b2c3d4-...",
  "status": "completed",
  "output_url": "https://api.pixelapi.dev/outputs/video.mp4",
  "processing_ms": 65000
}

cURL Example

# Generate video
curl -X POST https://api.pixelapi.dev/v1/video/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic shot of a golden retriever running through a field of wildflowers at sunset",
    "duration": 3,
    "resolution": "480p"
  }'

# Poll for result
curl https://api.pixelapi.dev/v1/video/GENERATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example

import requests, time

API_KEY = "pk_live_your_key"
headers = {"Authorization": f"Bearer {API_KEY}", "User-Agent": "MyApp/1.0"}

# Generate video
resp = requests.post("https://api.pixelapi.dev/v1/video/generate",
    headers=headers,
    json={
        "prompt": "A cinematic drone shot over mountains at sunrise, volumetric fog",
        "duration": 3,
        "resolution": "480p"
    }
)
gen_id = resp.json()["generation_id"]
print(f"Job queued: {gen_id}")

# Poll for result
while True:
    result = requests.get(f"https://api.pixelapi.dev/v1/video/{gen_id}", headers=headers).json()
    if result["status"] == "completed":
        print(f"Video URL: {result['output_url']}")
        break
    elif result["status"] in ("failed", "blocked"):
        print(f"Error: {result.get('error_message')}")
        break
    time.sleep(5)

Example Prompts

• "A golden retriever running through a field of wildflowers at sunset, cinematic, slow motion"
• "Ocean waves crashing on a rocky coastline, aerial drone shot, 4K quality"
• "A cozy coffee shop interior with steam rising from a cup, warm lighting"
• "Time-lapse of a city skyline from day to night, neon lights flickering on"
• "An astronaut floating in space with Earth in the background, cinematic lighting"

💎 Account Balance

{
  "credits_remaining": 9997.0,
  "plan": "starter",
  "email": "[email protected]"
}

📊 Usage History

Returns your recent job history with operations, models, status, and output URLs.

Python SDK Examples

Install

pip install pixelapi

Background Removal Workflow

from pixelapi import PixelAPI

client = PixelAPI("YOUR_API_KEY")

# Remove background from a product photo
result = client.remove_background("sneaker.jpg")
print(f"Transparent PNG: {result.url}")

# Replace background with AI lifestyle scene
result = client.replace_background(
    "sneaker.jpg",
    prompt="sneaker on concrete floor, urban alley, dramatic lighting, cinematic"
)
print(f"Lifestyle scene: {result.url}")

# Generate a product mockup from text
result = client.image.generate(
    prompt="Minimalist perfume bottle on marble, soft golden light, luxury",
    model="flux-schnell"
)
print(f"Generated: {result.url}")

# Upscale for print
result = client.upscale("product-low-res.jpg")
print(f"4x upscaled: {result.url}")

# Restore face in team photo
result = client.restore_face("team-photo.jpg")
print(f"Enhanced: {result.url}")

# Remove watermark
result = client.remove_object("photo.jpg", prompt="remove the watermark")
print(f"Cleaned: {result.url}")

Raw Python (no SDK)

import requests, time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.pixelapi.dev"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "MyApp/1.0"
}

# Remove background — file upload
with open("product.jpg", "rb") as f:
    resp = requests.post(
        f"{BASE}/v1/image/remove-background",
        headers=HEADERS,
        files={"image": f}
    )
gen_id = resp.json()["generation_id"]

# Poll for result
while True:
    time.sleep(2)
    result = requests.get(f"{BASE}/v1/image/{gen_id}", headers=HEADERS).json()
    if result["status"] == "completed":
        print(f"Done! {result['output_url']}")
        break
    elif result["status"] in ("failed", "blocked"):
        print(f"Error: {result['status']}")
        break

cURL Examples

# Remove background
curl -X POST https://api.pixelapi.dev/v1/image/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

# Replace background
curl -X POST https://api.pixelapi.dev/v1/image/replace-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]" \
  -F "prompt=product floating in clouds, ethereal lighting"

# Generate image
curl -X POST https://api.pixelapi.dev/v1/image/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{"model": "flux-schnell", "prompt": "Product photo of headphones"}'

# Upscale
curl -X POST https://api.pixelapi.dev/v1/image/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

# Restore face
curl -X POST https://api.pixelapi.dev/v1/image/restore-face \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]"

# Remove object
curl -X POST https://api.pixelapi.dev/v1/image/remove-object \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0" \
  -F "[email protected]" \
  -F "prompt=remove the text watermark"

# Check status (same for all operations)
curl https://api.pixelapi.dev/v1/image/GENERATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"

Node.js Example

const fs = require('fs');
const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://api.pixelapi.dev';

async function removeBackground(filePath) {
  const form = new FormData();
  form.append('image', new Blob([fs.readFileSync(filePath)]), 'image.jpg');

  const res = await fetch(`${BASE}/v1/image/remove-background`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'User-Agent': 'MyApp/1.0'
    },
    body: form
  });
  const { generation_id } = await res.json();

  // Poll for result
  while (true) {
    await new Promise(r => setTimeout(r, 2000));
    const status = await fetch(`${BASE}/v1/image/${generation_id}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'User-Agent': 'MyApp/1.0'
      }
    }).then(r => r.json());

    if (status.status === 'completed') return status.output_url;
    if (['failed', 'blocked'].includes(status.status)) throw new Error(status.status);
  }
}

removeBackground('product.jpg').then(url => console.log('Done:', url));

📋 Complete Sample Script

Save as pixelapi_demo.py and run. Zero dependencies — works with Python 3.6+.

#!/usr/bin/env python3
"""
PixelAPI Demo — Remove a product background in seconds.
Usage: python pixelapi_demo.py product.jpg
"""
import json, os, sys, time, urllib.request, urllib.error

API_KEY = "YOUR_API_KEY"
BASE = "https://api.pixelapi.dev"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "PixelAPI-Demo/1.0",
}

def api_post_file(path, file_path):
    """Upload a file via multipart/form-data"""
    import mimetypes
    boundary = "----PixelAPIBoundary"
    filename = os.path.basename(file_path)
    mime = mimetypes.guess_type(file_path)[0] or "application/octet-stream"
    with open(file_path, "rb") as f:
        file_data = f.read()
    body = (
        f"--{boundary}\r\n"
        f'Content-Disposition: form-data; name="image"; filename="{filename}"\r\n'
        f"Content-Type: {mime}\r\n\r\n"
    ).encode() + file_data + f"\r\n--{boundary}--\r\n".encode()
    headers = {**HEADERS, "Content-Type": f"multipart/form-data; boundary={boundary}"}
    req = urllib.request.Request(f"{BASE}{path}", data=body, headers=headers, method="POST")
    with urllib.request.urlopen(req, timeout=120) as r:
        return json.loads(r.read())

def api_get(path):
    req = urllib.request.Request(f"{BASE}{path}", headers=HEADERS)
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())

if len(sys.argv) < 2:
    print("Usage: python pixelapi_demo.py <image_file>")
    sys.exit(1)

image_file = sys.argv[1]
print(f"Removing background from {image_file}...")

# Submit
data = api_post_file("/v1/image/remove-background", image_file)
gen_id = data["generation_id"]
print(f"Job submitted: {gen_id[:12]}...")

# Poll
while True:
    time.sleep(2)
    result = api_get(f"/v1/image/{gen_id}")
    if result["status"] == "completed":
        print(f"\n✅ Done! Download your transparent PNG:")
        print(result["output_url"])
        break
    elif result["status"] in ("failed", "blocked"):
        print(f"\n❌ {result['status']}")
        sys.exit(1)
    print(".", end="", flush=True)

Error Handling

Error responses include a detail field:

{
  "detail": "Insufficient credits. Required: 2, available: 0. Upgrade at https://pixelapi.dev/app/#pricing"
}

Content Policy

PixelAPI uses automated content safety filters. Generated content is scanned for:

• NSFW / explicit content
• Violence and gore
• Real person deepfakes
• Hate speech and discriminatory content
• Illegal activity

Blocked jobs return status: "blocked". No credits are charged for blocked jobs.

FAQ

How do I sign up?

Go to pixelapi.dev/app and click "Sign in with Google". You get 10 free credits instantly — no credit card required.

What's a credit?

Credits are our billing unit. Each operation costs a specific number of credits: background removal = 2, background replace = 5, image generation = 3, upscaling = 20, face restoration = 3, object removal = 5.

Do credits expire?

Monthly credits reset on your billing cycle. Unused credits don't roll over.

How long are output URLs valid?

Output URLs expire after 24 hours. Download images promptly or store them yourself.

What image formats are accepted?

JPEG, PNG, and WebP. Maximum file size is 10MB. Maximum resolution is 4096×4096 pixels.

Can I use processed images commercially?

Yes. All images processed through PixelAPI are yours to use commercially.

How is the quality compared to remove.bg?

We use state-of-the-art segmentation models. Quality is comparable — we handle complex edges, hair, transparent objects, and fine details. And we do it at 1/35th the price.

Is there a webhook / callback option?

Webhooks are available on Pro and Scale plans. Contact support for setup details.

Troubleshooting

Getting 403 Forbidden

Fix: Add User-Agent: MyApp/1.0 to every request.

# Python (requests)
headers = {
    "Authorization": "Bearer YOUR_KEY",
    "User-Agent": "MyApp/1.0"    # ← Required!
}

# Python (urllib) — MUST set manually
req = urllib.request.Request(url, headers={
    "Authorization": "Bearer YOUR_KEY",
    "User-Agent": "MyApp/1.0"
})

Getting 401 Unauthorized

Your API key is invalid or missing. Use Authorization: Bearer YOUR_KEY (not X-API-Key).

Getting 402 Insufficient Credits

You don't have enough credits for this operation. Check your balance with GET /v1/account/balance and upgrade your plan if needed.

Getting 429 Too Many Requests

You've hit the rate limit. Wait and retry. Check X-RateLimit-Reset header. Consider upgrading your plan for higher limits.

Upload fails with large files

Maximum file size is 10MB. Resize or compress your image before uploading. For upscaling, the input doesn't need to be high-res — that's the whole point!

Job stuck in "queued"

This can happen during high load. Wait up to 2 minutes. If still queued, retry. GPU queue is first-come-first-served, with priority plans getting faster processing.

Background removal quality issues

Tips for best results:

• Use high-contrast images where the subject is clearly distinguishable
• Higher resolution input = better edge detection
• If edges are rough, try the image at a different resolution
• Works best with products, people, and objects with clear boundaries

👗 Virtual Try-On

Virtually dress a person photo with any garment image using AI. Powered by our virtual try-on — works with standing, sitting, casual poses. No pose restrictions.

Request — JSON body

{
  "person_image": "<base64-encoded image>",     // required — JPG/PNG/WebP, base64 string (no data: prefix)
  "garment_image": "<base64-encoded image>",    // required — flat-lay or product photo
  "category": "upperbody"                       // required — see Category Values below
}

Category Values

Response

{
  "job_id": "a3f91b...",    // poll this to get the result
  "status": "queued",
  "credits_used": 25
}

Poll for result

GET /v1/virtual-tryon/jobs/{job_id}

{
  "status": "completed",          // queued | processing | completed | failed
  "result_image_b64": "<base64 PNG>",
  "inference_time_ms": 35000
}

Example — cURL

PERSON_B64=$(base64 -w0 person.jpg)
GARMENT_B64=$(base64 -w0 garment.jpg)

# Submit
JOB=$(curl -s -X POST https://api.pixelapi.dev/v1/virtual-tryon \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"person_image\": \"$PERSON_B64\",
    \"garment_image\": \"$GARMENT_B64\",
    \"category\": \"upperbody\"
  }")
JOB_ID=$(echo $JOB | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# Poll until done
curl -s "https://api.pixelapi.dev/v1/virtual-tryon/jobs/$JOB_ID" \
  -H "Authorization: Bearer YOUR_KEY"

Example — Python

import requests, base64, time

def b64(path):
    return base64.b64encode(open(path, "rb").read()).decode()

headers = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}

# Submit job
resp = requests.post("https://api.pixelapi.dev/v1/virtual-tryon", headers=headers, json={
    "person_image": b64("person.jpg"),
    "garment_image": b64("tshirt.jpg"),
    "category": "upperbody"
})
job_id = resp.json()["job_id"]

# Poll for result
while True:
    r = requests.get(f"https://api.pixelapi.dev/v1/virtual-tryon/jobs/{job_id}", headers=headers)
    d = r.json()
    if d["status"] == "completed":
        img_data = base64.b64decode(d["result_image_b64"])
        open("result.png", "wb").write(img_data)
        print("Saved result.png")
        break
    elif d["status"] == "failed":
        print("Failed:", d.get("error_message"))
        break
    time.sleep(5)

📸 Photo Guidelines for Best Results

Garment image: Use a flat-lay or product photo on a white/light background for the cleanest result. The garment should be the main subject of the image.

Error Responses

All error responses follow this structure:

{
  "detail": {
    "error": "image_too_small",
    "message": "Person image is too small (minimum 100px)...",
    "guidance": "Use a photo that is at least 300x400px...",
    "received_size": "48x32px"    // included when relevant
  }
}

Need help? support@pixelapi.dev · Home · Dashboard · Swagger UI

🧠 Smart Generate NEW

AI-powered content generation that auto-detects your intent and routes to the right renderer. Ask for an infographic, chart, diagram, logo, or image — the API figures out what you want and generates it instantly.

How It Works

Request

{
  "prompt": "A bar chart showing Q1 sales $50K, Q2 $75K, Q3 $90K, Q4 $120K",
  "width": 1024,   // optional, default 1024
  "height": 1024   // optional, default 1024
}

Response

{
  "generation_id": "5d598582-...",
  "status": "completed",
  "intent": "smart-chart",
  "credits_used": 3.0,
  "output_url": "/static/smart-outputs/5d598582-....png",
  "enhanced_prompt": null,
  "estimated_seconds": 0.0
}

Note: Charts, infographics, and diagrams return "status": "completed" immediately — no polling needed. Logos and standard images return "status": "queued" — poll GET /v1/image/{generation_id} until done.

cURL Example — Chart

curl -X POST https://api.pixelapi.dev/v1/image/smart-generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A pie chart showing market share: Chrome 65%, Safari 18%, Firefox 8%, Edge 5%, Other 4%"}'

cURL Example — Infographic

curl -X POST https://api.pixelapi.dev/v1/image/smart-generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "An infographic about 5 benefits of remote work: flexibility, no commute, cost savings, better work-life balance, increased productivity"}'

cURL Example — Diagram

curl -X POST https://api.pixelapi.dev/v1/image/smart-generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A flowchart: User submits order -> Payment processing -> Inventory check -> Ship order -> Deliver to customer"}'

Python Example

import requests

resp = requests.post(
    "https://api.pixelapi.dev/v1/image/smart-generate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"prompt": "A bar chart of monthly revenue: Jan $10K, Feb $15K, Mar $22K, Apr $30K"}
)
data = resp.json()
print(f"Intent: {data['intent']}, Credits: {data['credits_used']}")

# Charts/infographics/diagrams complete instantly
if data["status"] == "completed":
    print(f"Output: https://api.pixelapi.dev{data['output_url']}")
else:
    # Logos/images need polling
    import time
    while True:
        status = requests.get(
            f"https://api.pixelapi.dev/v1/image/{data['generation_id']}",
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        ).json()
        if status["status"] == "completed":
            print(f"Output: {status['output_url']}")
            break
        time.sleep(1)

Intent Detection Tips

• Charts: Include words like "bar chart", "pie chart", "line chart", or data with numbers
• Infographics: Use "infographic" or list multiple facts/points
• Diagrams: Use "flowchart", "diagram", or describe a process with arrows (→, ->)
• Logos: Include "logo" in your prompt
• Images: Anything else routes to AI text-to-image image generation with prompt enhancement