SynthID Removal API

import os
from synthid_client import upload_images, wait_for_batch, download_result

options = {"origin": "https://synthidremoval.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://synthidremoval.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

For a single file, send multipart form data directly. The response contains the image status URL. Keep the same idempotency key if this request needs retrying.

curl "https://synthidremoval.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://synthidremoval.com/api/v1/images/IMAGE_ID" \
  -H "Authorization: Bearer $SYNTHID_API_KEY"

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

Image credits and API keys

Use 1 credit per image, or 0.5 credits each when you upload 5 or more. Credits are used only when your completed image is ready to download. Failed or canceled unfinished images use no credits; completed results with quality warnings use the agreed credits.

The service sets credit usage automatically; upload requests contain no pricing parameter.

Your API key authorizes requests using your account's image credits. Keep keys on your server or in your automation tool's secret store. Keys cannot authorize sign-in or payments. Create up to five active keys and revoke them in Account. Revocation stops new requests; accepted jobs remain accessible through another active key on the same account.

Half-credit processing requires at least 5 valid uploads with enough credits reserved before work begins. If fewer qualify, nothing is processed and the reserved credits are released. Once processing starts, later failures or cancellations do not increase the credits used per completed image.

Available image credits include purchased credits and eligible bonuses; purchased credits are used first.

Retries and interrupted uploads

The helpers create one Idempotency-Key per operation and reuse it through up to three retries for transient failures. To resume after a restart, pass the original file list and idempotencyKey in Node.js options or idempotency_key in Python. Keep the same file contents, names and order.

Upload errors expose the retry key as error.idempotencyKey in Node.js or error.idempotency_key in Python, plus the operation ID/status URL when known. Per-file transfer errors appear in error.items. The helper finishes independent transfers before reporting an incomplete upload. Fix the cause and resume within the original ten-minute upload window; already-confirmed files are skipped.

Changed metadata returns 409. Identical retries reuse the existing operation, including after API-key replacement. Idempotency records last seven days. Terminal failed or rejected items need a new operation; retries do not start them again or duplicate completed charges.

Raw HTTP: one image or a batch

POST /api/v1/images is the creation endpoint for both. Send a JSON files array with 1–20 entries; the response has the same batch shape for one or many. The helpers above handle these steps 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. Inspect ordered items for any not_started outcomes. Only images covered by your available balance and queue capacity are admitted.
2. PUT each admitted file to its entry in uploads, using the supplied content type. Do not send your API key to the storage URL. Limit simultaneous file transfers to two.
3. POST to each confirmUrl with your API key. Confirmation validates the file and reserves its charge. Processing starts once admitted uploads are confirmed. Finish within ten minutes.
4. Poll the batch statusUrl. Download ready images individually using downloadUrl, or download all ready images through zipUrl.

Existing batch status, confirmation, cancellation and ZIP routes act on the operation returned by the creation endpoint. DELETE an image's status URL to cancel or delete it. POST to /api/v1/batches/BATCH_ID/cancel to cancel unfinished items. Deleting a completed result does not reverse its charge.

Polling and downloads

Use pollAfterSeconds: normally 15 seconds while queued and 5 while processing. Stop when it is zero and inspect each item. Status and download URLs are relative to https://synthidremoval.com and require your API key. Polling does not accelerate processing or extend retention.

Download each completed image within one hour. ZIP includes currently ready images and streams without storing another archive. Processing focuses on image quality; completion does not verify the removal of every provenance signal. There are no webhooks in this version.

n8n, Make and Zapier

For one image, use an HTTP request step with a secret Bearer credential and POST multipart/form-data to /api/v1/images. Map the binary file to image. Supply a stable record ID as the Idempotency-Key; let the tool generate the multipart boundary. No price field is needed.

For multiple images, use the JSON creation and per-file PUT/confirmation flow above. In n8n, choose an n8n Binary File field for multipart uploads. In Make, use HTTP's multipart file field. In Zapier, use an action supporting binary multipart uploads, or the JSON flow with a separate binary PUT. Add a delay and status request, then save each ready download as a binary file. No dedicated connector is needed.

Limits and errors

• JPEG, PNG or WebP; 15 MiB and 20 megapixels per image, up to 20 images per batch. No animation or unnormalized EXIF rotation. The single-file multipart convenience request has a 16 MiB total limit; this is not a combined batch-size limit.
• One unfinished batch per account, including website uploads; the processing queue admits up to 200 outstanding images at a time.
• Six creation requests and 120 other API requests per minute per account, shared across keys. Retries count. Honor Retry-After on 429 and 503 responses.
• Ten minutes to upload; six hours for processing admission; one hour to download each completed result. Batch access lasts until its processing deadline plus two hours.

Errors include a stable code and readable error. 400 means invalid input, 401 an invalid or revoked key, 402 insufficient balance, 409 conflicting idempotency data or unfinished work, 410 expiry, 429 a rate/concurrency limit and 503 unavailable processing capacity. The helpers report codes without logging credentials or signed URLs.

Read availableCredits, creditsPerImage and bulkCreditsPerImage with GET /api/v1/account; legacy cent fields remain for compatibility. Download the OpenAPI specification for all request and response schemas.