REST API

Base URL: https://removecolor.online/api/v1

Authentication

All requests require an API key via the Authorization header.

Authorization: Bearer rc_live_xxxxx

Live keys (rc_live_) consume credits. Test keys (rc_test_) are rejected in production.

Credits & Billing

Every successful image operation consumes exactly 1 credit — the same flat rate for remove-color and grayscale, regardless of image size, mode, or processing time. New accounts receive 100 free credits at signup.

Only requests that return HTTP 2xx with a generated image are charged. Failed requests (validation errors, unsupported images, size limits, rate limits, server errors) cost nothing.
Insufficient credits return HTTP 402 — credits exhausted. Purchase more at /settings/credits on this site (one-time Stripe checkout, credits never expire):{"code":"INSUFFICIENT_CREDITS","credits_required":1,"credits_available":0}
Successful responses include your updated balance:X-Credits-Used: 1, X-Credits-Remaining: 97

Endpoints

GET/v1/health

Returns service health status. No auth required.

GET/v1/capabilities

Returns supported formats, limits, and available options.

POST/v1/images/remove-color

Removes a color from an image. Returns binary PNG.

Parameters (multipart/form-data):

file	Image file (required)
target_color	Hex color like #00FF00 (optional if sample_x/y provided)
sample_x, sample_y	Pixel coordinates for auto color pickup (optional)
tolerance	0-100, default 20
mode	"connected" or "global"
edge_smooth	0-10, default 2

POST/v1/images/grayscale

Converts an image to grayscale (Rec.709). Returns binary PNG.

Examples

curl

curl -X POST \
  https://removecolor.online/api/v1/images/remove-color \
  -H "Authorization: Bearer rc_live_xxxxx" \
  -F "file=@photo.jpg" \
  -F "target_color=#00FF00" \
  -F "tolerance=20" \
  -F "mode=global" \
  -F "edge_smooth=2" \
  --output result.png

JavaScript

import fs from 'fs';

const file = fs.readFileSync('photo.jpg');
const form = new FormData();
form.append('file', new Blob([file]), 'photo.jpg');
form.append('target_color', '#00FF00');
form.append('tolerance', '20');
form.append('mode', 'global');
form.append('edge_smooth', '2');

const res = await fetch('https://removecolor.online/api/v1/images/remove-color', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer rc_live_xxxxx' },
  body: form,
});

const png = await res.arrayBuffer();
fs.writeFileSync('result.png', Buffer.from(png));

Python

import requests

url = 'https://removecolor.online/api/v1/images/remove-color'
headers = {'Authorization': 'Bearer rc_live_xxxxx'}
files = {'file': ('photo.jpg', open('photo.jpg', 'rb'), 'image/jpeg')}
data = {
    'target_color': '#00FF00',
    'tolerance': '20',
    'mode': 'global',
    'edge_smooth': '2',
}

res = requests.post(url, headers=headers, files=files, data=data)
with open('result.png', 'wb') as f:
    f.write(res.content)

Rate Limits

Default: 30 requests/minute per API key (HTTP 429 when exceeded), plus a daily safety valve of 5,000 requests/day. These limits are anti-abuse protections that sit on top of credits — Rate Limit ≠ Credit Balance. Credits are the usage entitlement: 1 credit per successful request. Failed requests count toward the rate limits but never consume credits.

OpenAPI

Full OpenAPI 3.1 spec available at /api/openapi.json /api/openapi.json