API Reference

Automate background removal with a simple HTTP API. Pay per processed image from your account balance.

Overview

The Foner API v1 lets you remove backgrounds from images programmatically. Send a photo as multipart upload or by URL, poll for completion (or wait up to 30 seconds in sync mode), then download the cutout in PNG, WebP, or JPEG.

Authentication

Every request must include your API key in the X-API-Key header. Keys start with fnr_ and are shown only once when created. Revoked keys stop working immediately.

Create and manage API keys in your account profile

Use Foner from AI assistants via MCP — see the MCP setup page

Endpoints

Method	Path	Description
POST	/v1/remove-bg	Upload an image (multipart file or image_url form field). Query async=true returns immediately with job_id. Sync mode waits up to 30 s, then returns the result or 202 with job_id.
GET	/v1/jobs/{job_id}	Get job status, error code, and download_url when processing is complete.
GET	/v1/jobs/{job_id}/download	Download the result. Query format=png\|webp\|jpeg and bg=RRGGBB for JPEG background color.
GET	/v1/account	Balance, price per image, and job statistics for the API key owner.

curl examples

Remove background (sync)

Waits up to 30 seconds for the result. On timeout returns 202 with job_id.

curl -X POST "https://foner.site/v1/remove-bg" \
  -H "X-API-Key: fnr_your_key_here" \
  -F "file=@photo.jpg"

Remove background (async)

Returns 202 immediately with job_id and status queued.

curl -X POST "https://foner.site/v1/remove-bg?async=true" \
  -H "X-API-Key: fnr_your_key_here" \
  -F "file=@photo.jpg"

Get job status

curl "https://foner.site/v1/jobs/{job_id}" \
  -H "X-API-Key: fnr_your_key_here"

Download result

curl -o result.png \
  "https://foner.site/v1/jobs/{job_id}/download?format=png" \
  -H "X-API-Key: fnr_your_key_here"

Account info

curl "https://foner.site/v1/account" \
  -H "X-API-Key: fnr_your_key_here"

Code snippets

Python (httpx)

import httpx

API_KEY = "fnr_your_key_here"
headers = {"X-API-Key": API_KEY}

with open("photo.jpg", "rb") as f:
    response = httpx.post(
        "https://foner.site/v1/remove-bg",
        headers=headers,
        files={"file": ("photo.jpg", f, "image/jpeg")},
        timeout=60,
    )
print(response.json())

Node.js (fetch)

import { readFileSync } from "node:fs";

const API_KEY = "fnr_your_key_here";
const form = new FormData();
form.append("file", new Blob([readFileSync("photo.jpg")]), "photo.jpg");

const response = await fetch("https://foner.site/v1/remove-bg", {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
  body: form,
});
console.log(await response.json());

PHP (curl)

$ch = curl_init("https://foner.site/v1/remove-bg");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: fnr_your_key_here"],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("photo.jpg")],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);

Error codes

HTTP status	Meaning
401	Missing or invalid API key (missing_api_key, invalid_api_key).
402	Insufficient balance to start processing (insufficient_funds).
403	Email address not verified (email_not_verified).
404	Job not found or does not belong to this key (job_not_found).
422	Validation error: invalid image, unsupported format, missing file/URL, or processing failed.
429	Rate limit exceeded for this API key (rate_limited).

Limits

• 300 requests per hour per API key
• Maximum file size: 25 MB
• Maximum image resolution: 32 megapixels
• Minimum balance to start a job: $0.10 (current price per image)