Dokumentasi API

Mulai cepat

Permintaan pertama Anda hanya memerlukan input.image_base64. Abaikan input.output untuk mempertahankan keluaran transparan berukuran asli yang digunakan klien lama.

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"}}'

Autentikasi dengan Bearer key

Buat API Key dari Personal, lalu kirimkan melalui header Authorization untuk setiap permintaan.

Authorization: Bearer rz_live_your_api_key

• Simpan kunci dalam variabel lingkungan server atau pengelola rahasia.
• Jangan pernah menaruh kunci di kode browser, paket aplikasi seluler, ekstensi, URL, repositori publik, atau log.
• Gunakan kunci terpisah untuk layanan atau lingkungan berbeda bila memungkinkan.
• Segera cabut dan ganti kunci jika mungkin telah terekspos.

Panggil API dari server Anda

Gunakan jalur browser atau klien → server Anda → RemoveZero API. Bearer key dapat mengotorisasi pemrosesan berbayar, sehingga klien publik tidak dapat menjaganya tetap rahasia. Permintaan server berbayar harus menghilangkan header Origin.

Kirim permintaan penghapusan latar

Kirim satu permintaan JSON ketat dari server Anda. Header wajib divalidasi sebelum reservasi Credit atau pemrosesan gambar.

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 harus application/json; parameter charset diperbolehkan.
• Content-Encoding harus dihilangkan atau bernilai identity; body permintaan terkompresi ditolak.
• Jangan kirim header Origin.
• Idempotency-Key harus terdiri dari 1–128 karakter berupa huruf, angka, titik, garis bawah, titik dua, atau tanda hubung.
• image_base64 harus berisi byte gambar Base64 standar tanpa awalan data:image/....

Sesuaikan keluaran

Objek input.output bersifat opsional. Objek ini mengubah kanvas setelah satu inferensi penghapusan latar yang sama, sehingga penyesuaian tidak menggunakan Credit tambahan.

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

Perilaku contain + center yang tetap

Fit bukan field permintaan. RemoveZero selalu mempertahankan rasio aspek subjek dan memasukkannya ke dalam kanvas yang tersedia.

• Seluruh subjek tetap terlihat dan berada di tengah.
• Subjek tidak dipotong atau diregangkan.
• Sisa ruang kanvas menggunakan transparansi atau warna yang diminta.
• Cover, smart crop, posisi gravity, dan koordinat arbitrer tidak didukung.

Kompatibilitas mundur

Klien lama dapat menghilangkan input.output dan tetap hanya mengirim input.image_base64. Tambahkan output hanya jika memerlukan format, latar, kanvas, atau padding khusus.

Respons berhasil

Gambar yang berhasil mengembalikan HTTP 200 dan menggunakan 1 Credit. Keluaran mencakup content type dan dimensi kanvas yang tepat, serta data Base64 yang dapat didekode oleh server Anda.

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
  }
}

Dekode hasil

1. Konfirmasikan HTTP 200, ok: true, dan status: COMPLETED.
2. Baca output.content_type dan hanya terima image/png atau image/webp.
3. Dekode output.output_base64 satu kali dan simpan byte dengan ekstensi yang sesuai.
4. Jika dimensi diminta, verifikasi output.width dan output.height.

Hasil dikembalikan secara langsung, bukan sebagai URL permanen. Simpan byte hasil dekode di aplikasi Anda jika perlu menyimpan atau mengirimkan gambar.

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"));

Penagihan dan pengembalian Credit

Setiap permintaan memproses satu gambar. RemoveZero memvalidasi permintaan, mencadangkan 1 Credit secara atomik, dan menyelesaikannya hanya setelah penghapusan latar dan keluaran yang diminta berhasil. Penyesuaian keluaran tidak pernah menambah inferensi atau Credit.

Siklus Credit

Jika permintaan atau pengembaliannya belum dapat diverifikasi, API mengembalikan REFUND_PENDING dengan request ID dan Retry-After: 30. Pertahankan Idempotency-Key yang sama dan jangan kirim gambar yang sama dengan kunci baru.

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

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

Idempotensi dan percobaan ulang

Idempotency-Key mengikat body JSON yang diserialisasi secara tepat, termasuk gambar dan setiap field output yang diberikan. Simpan byte permintaan asli bersama kuncinya.

• Kunci sama dan body benar-benar sama: aman dicoba ulang tanpa reservasi atau permintaan pemrosesan kedua.
• Kunci sama dan body berubah: 409 IDEMPOTENCY_CONFLICT.
• Kunci sama setelah permintaan terminal: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; hasil Base64 yang selesai tidak disimpan untuk replay.
• Kunci baru: permintaan baru yang dapat mencadangkan Credit lagi.
• Body JSON yang secara semantik sama tetap dapat berbeda jika spasi, urutan properti, atau default eksplisit berubah.

Panduan Retry-After

429 RATE_LIMITED

Tunggu 60 detik, lalu coba ulang body yang sama dengan kunci yang sama.

503 REFUND_PENDING

Tunggu 30 detik, lalu coba ulang body yang sama dengan kunci yang sama.

503 UPSTREAM_BUSY

Tunggu 10 detik. Gunakan kunci baru hanya untuk percobaan baru yang disengaja.

Timeout jaringan atau API_UNAVAILABLE

Anggap hasilnya belum diketahui dan simpan body serta kunci asli hingga terselesaikan.

Contoh

Ganti placeholder di server Anda. API key tidak boleh terekspos dalam paket browser publik.

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}}}'

Titik awal keluaran umum

Resep ini adalah titik awal, bukan jaminan kepatuhan permanen untuk marketplace atau kategori. Nama platform hanyalah label, bukan nilai enum 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}

Error dan pemecahan masalah

Error menggunakan status HTTP yang stabil dan kode singkat dalam respons JSON.

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

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

Pemecahan masalah yang aman

1. Catat status HTTP, kode error, request_id jika ada, stempel waktu, dan Idempotency-Key Anda.
2. Jangan pernah mencatat atau mengirim Bearer key, image_base64 lengkap, atau respons lengkap yang berisi data gambar.
3. Perbaiki error 4xx terkait permintaan, kredensial, saldo, atau header sebelum mencoba lagi.
4. Patuhi Retry-After dan pertahankan body serta kunci asli untuk permintaan yang belum terselesaikan.
5. Hubungi dukungan dengan pengenal non-rahasia jika status belum terselesaikan terus berlanjut.

Batas permintaan

Kirim satu gambar JPG, PNG, atau WebP per permintaan sebagai Base64 standar. Input hasil dekode maksimal 5 MiB dan body JSON lengkap maksimal 7.500.000 byte. Keluaran khusus dibatasi hingga 4.096 px per sisi dan 4.194.304 piksel. Jika hasil persis yang diminta tidak muat dalam batas respons inline, pemrosesan gagal dan Credit yang dicadangkan dikembalikan; API tidak pernah diam-diam mengubah ukuran atau format yang diminta.