european_flag100% 欧洲
Integration guides

Guides for integrating Removit API

These guides translate the endpoint reference into practical backend integration paths for remote uploads, multipart uploads, asynchronous API polling, and delivery_mode choices.

Use them when you already understand the API contract and want concrete examples for a production image processing API workflow.

What these guides cover

Each guide focuses on one implementation decision: remote uploads, multipart uploads, polling, delivery strategy, processing modes, and end-to-end examples.

Remote URL upload

Best when the source image is already hosted and reachable via HTTP or HTTPS.

Multipart upload

Useful when the file is still local or not publicly available yet.

Polling strategy

How to track queued and pending jobs until the final state becomes done.

delivery_mode selection

How to choose between final_url and final_urls depending on the integration complexity.

Mode selection

When to use background, clipping or params for different image processing workflows.

Backend examples

How to structure a complete upload-and-poll loop in real integration code.

Guide 1: Upload with a remote URL

This mode is ideal when the source image is already available online and can be reached publicly through HTTP or HTTPS.

Key takeaways

Use these notes to decide when the guide pattern is the right fit for your integration.

  • Simple JSON integration with no multipart handling.
  • Good fit for backend pipelines and orchestrated catalog jobs.
  • Use only valid public http or https source URLs.
Remote upload example

Upload a file_url payload

This request creates a params job from a remote image URL and asks for all generated URLs.

curl -X POST "https://api.removit.eu/api/v1/upload" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "file_url": "https://example.com/image.jpg",
    "mode": "params",
    "params": "mon_set",
    "delivery_mode": "url",
    "output_format": "webp"
  }'

Guide 2: Upload a local file directly

This mode is useful when the source file is not yet available through a public URL and must be pushed directly from a backend server.

Key takeaways

Use these notes to decide when the guide pattern is the right fit for your integration.

  • Do not send file and file_url in the same request.
  • Validate the file MIME type before forwarding it to the API.
  • Prefer backend uploads so the API key never reaches the browser.
Multipart example

Direct file upload

This multipart request sends a local file and asks for a resolved final URL.

curl -X POST "https://api.removit.eu/api/v1/upload" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -F "file=@/path/to/image.jpg" \
  -F "mode=params" \
  -F "params=mon_set" \
  -F "delivery_mode=final_url"

Guide 3: Poll job status correctly

After the upload, jobs can remain queued or in a pending_* stage for some time. The client should keep polling until state=done.

01

Start the upload

Create the job and persist the returned job_id immediately.

02

Store job_id safely

Treat job_id as the canonical reference for all subsequent polling requests.

03

Poll /status with backoff

Call the status endpoint every 2 to 5 seconds and increase the interval gradually if needed.

04

Set a business timeout

Define your own timeout or escalation threshold on the client or backend side.

05

Read the final output

Stop polling when state=done, then use final_url or final_urls depending on delivery_mode.

Guide 4: Choose delivery_mode intentionally

delivery_mode changes the shape of the finished result, which affects how simple or technical your consumer code needs to be.

delivery_mode=url

Use this when you want multiple intermediate and final variations such as background, compose, shadowTop, and clipping.

delivery_mode=final_url

Use this when you want a single resolved final asset and a simpler consumer integration.

Guide 5: Understand processing modes

mode defines the requested workflow and shapes the expected output behavior.

background

Use this for a background-oriented output workflow.

clipping

Use this when the target output is clipping, with fallback behavior toward background when relevant.

params

Use this when you want to apply a parameter set, optionally preserve shadow, and generate multiple variations.

Guide 6: Full integration notes

A full integration usually combines a backend upload route, polling persistence, and a small orchestration layer around status transitions.

JavaScript

Suitable for backend runtimes, workers, and API routes that can manage async polling loops.

PHP

Useful for ecommerce backends or middleware layers that already orchestrate remote asset workflows.

Python

A good fit for batch workers, automation scripts, and ingestion pipelines.

cURL

Useful for manual validation, smoke tests, and API contract checks.

JavaScript example

Upload and poll in one backend flow

This example uploads a remote image, checks the accepted response, then polls until the job is done.

const BASE_URL = "https://api.removit.eu";
const API_KEY = "<YOUR_API_KEY>";

async function uploadAndPoll() {
  const uploadRes = await fetch(`${BASE_URL}/api/v1/upload`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      file_url: "https://example.com/image.jpg",
      mode: "params",
      params: "mon_set",
      delivery_mode: "final_url"
    })
  });

  const upload = await uploadRes.json();
  if (uploadRes.status !== 202) throw new Error(JSON.stringify(upload));

  const jobId = upload.job_id;

  while (true) {
    const statusRes = await fetch(
      `${BASE_URL}/api/v1/status?job_id=${encodeURIComponent(jobId)}`,
      { headers: { "X-API-Key": API_KEY } }
    );

    const status = await statusRes.json();
    if (status.state === "done") return status;

    await new Promise((r) => setTimeout(r, 3000));
  }
}