SynthID Remover API

import os
from synthid_client import upload_images, wait_for_batch, download_result

options = {"origin": "https://www.synthidremover.com", "api_key": os.environ["SYNTHID_API_KEY"]}
# One path or a list of up to 20 paths; 15 MiB per image.
batch = upload_images(["image.png", "photo.jpg"], **options)
# Save these if your application needs to resume later.
print("Operation:", batch["id"], "Retry key:", batch["idempotencyKey"])
batch = wait_for_batch(batch, **options)
for item in batch["items"]:
    if item["state"] != "ready":
        print("Not ready:", item["ordinal"], item.get("code") or item["state"])
        continue
    if item.get("warning"):
        print(item["warning"])
    download_result(item["downloadUrl"], f"result-{item['ordinal'] + 1}.png", **options)

# Or download all ready images in one archive:
# download_result(batch["zipUrl"], "results.zip", **options)

import { uploadImages, waitForBatch, downloadResult } from "./synthid-client.mjs";

const options = { origin: "https://www.synthidremover.com", apiKey: process.env.SYNTHID_API_KEY };
// One path or a list of up to 20 paths; 15 MiB per image.
let batch = await uploadImages(["image.png", "photo.jpg"], options);
// Save these if your application needs to resume later.
console.log("Operation:", batch.id, "Retry key:", batch.idempotencyKey);
batch = await waitForBatch(batch, options);
for (const item of batch.items) {
  if (item.state !== "ready") {
    console.log("Not ready:", item.ordinal, item.code || item.state);
    continue;
  }
  if (item.warning) console.warn(item.warning);
  await downloadResult(item.downloadUrl, "result-" + (item.ordinal + 1) + ".png", options);
}

// Or download all ready images in one archive:
// await downloadResult(batch.zipUrl, "results.zip", options);

One image with cURL

Send a single file directly as multipart form data. The image status URL is returned in the response. Reuse the idempotency key when retrying that request.

curl "https://www.synthidremover.com/api/v1/images" \
  -H "Authorization: Bearer $SYNTHID_API_KEY" \
  -H "Idempotency-Key: my-upload-0001" \
  -F "image=@image.png;type=image/png"

# Poll the returned statusUrl with the same API key.
curl "https://www.synthidremover.com/api/v1/images/IMAGE_ID" \
  -H "Authorization: Bearer $SYNTHID_API_KEY"

# Once state is ready, download the returned downloadUrl.
curl "https://www.synthidremover.com/api/v1/images/IMAGE_ID/download" \
  -H "Authorization: Bearer $SYNTHID_API_KEY" -o result.png

Image credits and API keys

Each image uses 1 credit, or 0.5 credits each when you upload 5 or more. Your credits are deducted only when your completed image is ready to download. No credits are used for failed images or cancellations before completion; completed results with quality warnings use the agreed credits.

Credit usage is determined by the service, so no pricing parameter belongs in an upload request.

An API key lets requests use the image credits in your account. Store keys on a server or in the secret store of your automation tool. They do not grant sign-in or payment permissions. Account lets you create and revoke up to five active keys. Revoking a key blocks new requests, while another active key for the same account can still access accepted jobs.

To use half a credit per image, at least 5 uploads must pass validation and have credits reserved before processing. Fewer eligible images means no processing and all reserved credits are freed. After work begins, failures or cancellations leave the per-image credit amount unchanged.

Both purchased and eligible bonus credits are available for image processing, with purchased credits used first.

Retries and interrupted uploads

The helpers generate a single Idempotency-Key for each operation and reuse it for up to three retries of transient failures. After restarting, resume with the original file list and idempotencyKey in Node.js options or idempotency_key in Python. Preserve the file contents, filenames and ordering.

Upload errors provide the retry key as error.idempotencyKey in Node.js or error.idempotency_key in Python, along with the operation ID/status URL when known. Find file-transfer errors in error.items. The helper lets independent transfers finish before it reports an incomplete upload. Correct the problem and resume within the initial ten-minute window; files already confirmed are skipped.

Metadata changes cause a 409 response. An identical retry uses the original operation even if the API key has been replaced. Idempotency records are retained for seven days. A new operation is needed for terminal failures or rejected items; retries neither restart them nor repeat completed charges.

Raw HTTP: one image or a batch

POST /api/v1/images creates both single-image and batch operations. Provide a JSON files array of 1–20 entries; one-image and multiple-image responses have the same batch structure. The supplied helpers perform this sequence automatically.

POST /api/v1/images
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: my-upload-0001
Content-Type: application/json

{
  "files": [
    { "filename": "image.png", "contentType": "image/png", "sizeBytes": 123456 },
    { "filename": "photo.jpg", "contentType": "image/jpeg", "sizeBytes": 234567 }
  ]
}

1. Check ordered items for not_started outcomes. Admission requires both available balance and room in the queue.
2. Send each admitted file with PUT to its entry in uploads, using the supplied content type. Keep your API key out of requests to the storage URL. Transfer no more than two files simultaneously.
3. Call each confirmUrl with your API key using POST. Confirmation checks the file and reserves the image charge. After admitted uploads are confirmed, processing begins. Complete this within ten minutes.
4. Check status by polling the batch statusUrl. Retrieve ready files one by one from downloadUrl, or collect all ready images with zipUrl.

Batch status, confirmation, cancellation and ZIP routes refer to the operation returned at creation. Cancel or delete an image by sending DELETE to its status URL. To cancel unfinished images, POST to /api/v1/batches/BATCH_ID/cancel. The charge for a completed result remains after deletion.

Polling and downloads

Follow the returned pollAfterSeconds: usually 15 seconds in the queue and 5 during processing. At zero, stop polling and check every item. Status and download URLs resolve against https://www.synthidremover.com and require an API key. Polling neither speeds processing nor extends retention.

Save every completed result within one hour. ZIP streams the currently ready files without saving a separate archive. Processing prioritizes image quality, but a finished output does not confirm that all provenance signals are absent. This version provides no webhooks.

n8n, Make and Zapier

For a single image, configure an HTTP request step using a secret Bearer credential and POST multipart/form-data to /api/v1/images. Assign the binary file to image. Use a stable record identifier for Idempotency-Key and allow the tool to generate the multipart boundary. Leave out any price field.

Use the preceding JSON creation and per-file PUT/confirmation steps for several images. For multipart uploads in n8n, select an n8n Binary File field. For Make, choose the HTTP multipart file field. A Zapier action must support binary multipart uploads, or use JSON creation with a separate binary PUT. Include a delay and status request before saving each ready download as a binary file. A dedicated connector is unnecessary.

Limits and errors

• Use JPEG, PNG or WebP with up to 15 MiB and 20 megapixels per image, and up to 20 images per batch. Animation and unnormalized EXIF rotation are unsupported. The direct single-file multipart request has a total 16 MiB limit, separate from batch limits.
• Each account can have one unfinished batch, counting website uploads, while the processing queue accepts up to 200 outstanding images.
• Per account, the per-minute limits are six creation requests and 120 other API requests, shared by its keys. Retries use this allowance. Respect Retry-After with 429 and 503 responses.
• You have ten minutes to upload, six hours for processing admission and one hour to download each completed image. Batch access ends two hours after its processing deadline.

An error contains a stable code and readable error. The status meanings are: 400 invalid input, 401 invalid or revoked key, 402 insufficient balance, 409 conflicting idempotency data or unfinished work, 410 expiry, 429 rate/concurrency limit, and 503 unavailable processing capacity. Helpers report the codes without logging credentials or signed URLs.

Use GET /api/v1/account to retrieve availableCredits, creditsPerImage and bulkCreditsPerImage, alongside legacy cent fields retained for compatibility. For complete request and response schemas, download the OpenAPI specification.