Documentazione API

Avvio rapido

La prima richiesta richiede solo input.image_base64. Ometti input.output per mantenere l'output trasparente nelle dimensioni originali usato dai client esistenti.

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

Autenticazione con una chiave Bearer

Crea una chiave API nell'area Personale e inviala nell'header Authorization di ogni richiesta.

Authorization: Bearer rz_live_your_api_key

• Conserva le chiavi in una variabile d'ambiente del server o in un gestore dei segreti.
• Non inserire mai una chiave nel codice del browser, in app mobili, estensioni, URL, repository pubblici o log.
• Quando possibile, usa chiavi distinte per servizi o ambienti diversi.
• Revoca e sostituisci subito una chiave che potrebbe essere stata esposta.

Chiama l'API dal tuo server

Usa il percorso browser o client → il tuo server → API RemoveZero. La chiave Bearer autorizza l'elaborazione a pagamento, quindi un client pubblico non può mantenerla segreta. Le richieste server a pagamento devono omettere l'header Origin.

Invia una richiesta di rimozione dello sfondo

Invia dal server una richiesta JSON rigorosa. Gli header obbligatori vengono convalidati prima della riserva dei Crediti o dell'elaborazione.

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Type deve essere application/json; è consentito un parametro charset.
• Content-Encoding deve essere omesso o identity; i corpi compressi vengono rifiutati.
• Non inviare l'header Origin.
• Idempotency-Key deve contenere 1–128 caratteri tra lettere, numeri, punti, trattini bassi, due punti o trattini.
• image_base64 deve contenere i byte dell'immagine in Base64 standard senza prefisso data:image/....

Personalizza l'output

L'oggetto input.output è facoltativo. Modifica la tela dopo la stessa singola inferenza di rimozione, quindi la personalizzazione non usa un altro Credito.

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

Comportamento fisso di contenimento e centratura

L'adattamento non è un campo della richiesta. RemoveZero conserva sempre le proporzioni del soggetto e lo inserisce nello spazio disponibile.

• Il soggetto completo resta visibile e centrato.
• Il soggetto non viene ritagliato né deformato.
• Lo spazio restante usa trasparenza o il colore richiesto.
• Non sono supportati cover, ritaglio intelligente, posizioni gravity o coordinate arbitrarie.

Compatibilità con le versioni precedenti

I client esistenti possono omettere input.output e continuare a inviare solo input.image_base64. Aggiungi output solo per formato, sfondo, tela o margine personalizzati.

Risposta riuscita

Un'immagine completata restituisce HTTP 200 e utilizza 1 Credito. L'output include tipo di contenuto, dimensioni esatte della tela e dati Base64 da decodificare sul server.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

Decodifica il risultato

1. Conferma HTTP 200, ok: true e status: COMPLETED.
2. Leggi output.content_type e accetta solo image/png o image/webp.
3. Decodifica output.output_base64 una volta e salva i byte con l'estensione corretta.
4. Se hai richiesto dimensioni, verifica output.width e output.height.

Il risultato viene restituito direttamente, non come URL permanente. Salva i byte decodificati nella tua applicazione se devi conservare o distribuire l'immagine.

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

Addebiti e restituzione dei Crediti

Ogni richiesta elabora un'immagine. RemoveZero convalida la richiesta, riserva atomicamente 1 Credito e lo contabilizza solo dopo la riuscita della rimozione e dell'output richiesto. La personalizzazione non aggiunge un'altra inferenza o Credito.

Ciclo di vita del Credito

Se la richiesta o il rimborso non sono ancora verificabili, l'API restituisce REFUND_PENDING con ID richiesta e Retry-After: 30. Mantieni la stessa Idempotency-Key e non inviare la stessa immagine con una chiave nuova.

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

Idempotenza e nuovi tentativi

Idempotency-Key è legata al corpo JSON serializzato esatto, inclusi immagine e campi di output. Conserva i byte originali della richiesta e la chiave.

• Stessa chiave e corpo identico: nuovo tentativo sicuro senza seconda riserva o elaborazione.
• Stessa chiave e corpo modificato: 409 IDEMPOTENCY_CONFLICT.
• Stessa chiave dopo una richiesta terminale: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; i risultati Base64 completati non vengono conservati per il replay.
• Chiave nuova: nuova richiesta che può riservare un altro Credito.
• Un JSON semanticamente uguale può differire se cambiano spazi, ordine delle proprietà o valori predefiniti espliciti.

Indicazioni Retry-After

429 RATE_LIMITED

Attendi 60 secondi e riprova il corpo esatto con la stessa chiave.

503 REFUND_PENDING

Attendi 30 secondi e riprova il corpo esatto con la stessa chiave.

503 UPSTREAM_BUSY

Attendi 10 secondi. Usa una chiave nuova solo per un nuovo tentativo intenzionale.

Timeout di rete o API_UNAVAILABLE

Considera l'esito sconosciuto e conserva corpo e chiave originali fino alla risoluzione.

Esempi

Sostituisci i segnaposto sul server. La chiave API non deve mai essere esposta in un bundle pubblico del browser.

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

Configurazioni iniziali comuni

Queste configurazioni sono punti di partenza, non garanzie permanenti di conformità. I nomi delle piattaforme sono etichette, non valori enum dell'API.

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

Errori e risoluzione dei problemi

Gli errori usano uno stato HTTP stabile e un codice breve nella risposta JSON.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

Risoluzione sicura dei problemi

1. Registra stato HTTP, codice di errore, request_id se presente, data e ora e Idempotency-Key.
2. Non registrare né inviare mai la chiave Bearer, image_base64 completo o una risposta completa con dati immagine.
3. Correggi gli errori 4xx di richiesta, credenziali, saldo o header prima di riprovare.
4. Rispetta Retry-After e conserva corpo e chiave originali per le richieste non risolte.
5. Contatta l'assistenza con identificatori non segreti se lo stato persiste.

Limiti della richiesta

Invia un'immagine JPG, PNG o WebP per richiesta in Base64 standard. L'input decodificato può essere al massimo 5 MiB e il corpo JSON completo 7.500.000 byte. L'output personalizzato è limitato a 4.096 px per lato e 4.194.304 pixel. Se il risultato esatto supera il limite della risposta diretta, l'elaborazione fallisce e il Credito riservato viene restituito; l'API non modifica mai in silenzio dimensioni o formato.