Tài liệu API

Bắt đầu nhanh

Yêu cầu đầu tiên chỉ cần input.image_base64. Bỏ qua input.output để giữ đầu ra trong suốt ở kích thước gốc như các client hiện có.

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

Xác thực bằng Bearer key

Tạo API Key trong Personal rồi gửi khóa đó trong header Authorization của mọi yêu cầu.

Authorization: Bearer rz_live_your_api_key

• Giữ khóa trong biến môi trường máy chủ hoặc trình quản lý bí mật.
• Không đặt khóa trong mã trình duyệt, gói ứng dụng di động, tiện ích mở rộng, URL, kho mã công khai hoặc log.
• Dùng khóa riêng cho từng dịch vụ hoặc môi trường khi phù hợp.
• Thu hồi và thay khóa ngay nếu có khả năng bị lộ.

Gọi API từ máy chủ của bạn

Dùng luồng trình duyệt hoặc client → máy chủ của bạn → RemoveZero API. Bearer key có thể cho phép xử lý trả phí nên client công khai không thể giữ bí mật. Yêu cầu máy chủ trả phí phải bỏ header Origin.

Gửi yêu cầu xóa nền

Gửi một yêu cầu JSON nghiêm ngặt từ máy chủ. Các header bắt buộc được kiểm tra trước khi giữ Credit hoặc xử lý ảnh.

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 phải là application/json; có thể kèm tham số charset.
• Content-Encoding phải được bỏ qua hoặc là identity; body nén sẽ bị từ chối.
• Không gửi header Origin.
• Idempotency-Key phải dài 1–128 ký tự, chỉ gồm chữ cái, số, dấu chấm, gạch dưới, dấu hai chấm hoặc gạch ngang.
• image_base64 phải chứa byte ảnh Base64 chuẩn, không có tiền tố data:image/....

Tùy chỉnh đầu ra

Đối tượng input.output là tùy chọn. Nó thay đổi khung sau cùng một lần suy luận xóa nền, vì vậy tùy chỉnh không dùng thêm Credit.

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

Cách contain + center cố định

Fit không phải field của yêu cầu. RemoveZero luôn giữ tỷ lệ chủ thể và đặt vừa trong khung khả dụng.

• Toàn bộ chủ thể vẫn hiển thị và được căn giữa.
• Chủ thể không bị cắt hoặc kéo giãn.
• Phần trống của khung dùng độ trong suốt hoặc màu được yêu cầu.
• Không hỗ trợ cover, smart crop, vị trí gravity hoặc tọa độ tùy ý.

Khả năng tương thích ngược

Client hiện có có thể bỏ input.output và tiếp tục chỉ gửi input.image_base64. Chỉ thêm output khi cần định dạng, nền, khung hoặc khoảng đệm tùy chỉnh.

Phản hồi thành công

Ảnh thành công trả về HTTP 200 và dùng 1 Credit. Đầu ra có content type, kích thước khung chính xác và dữ liệu Base64 để máy chủ giải mã.

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

Giải mã kết quả

1. Xác nhận HTTP 200, ok: true và status: COMPLETED.
2. Đọc output.content_type và chỉ chấp nhận image/png hoặc image/webp.
3. Giải mã output.output_base64 một lần và lưu byte với phần mở rộng phù hợp.
4. Nếu đã yêu cầu kích thước, hãy kiểm tra output.width và output.height.

Kết quả được trả trực tiếp, không phải URL vĩnh viễn. Hãy lưu byte đã giải mã trong ứng dụng nếu cần giữ hoặc phân phối ảnh.

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

Thanh toán và hoàn Credit

Mỗi yêu cầu xử lý một ảnh. RemoveZero xác thực yêu cầu, giữ nguyên tử 1 Credit và chỉ quyết toán sau khi cả xóa nền lẫn đầu ra yêu cầu thành công. Tùy chỉnh đầu ra không bao giờ thêm lần suy luận hoặc Credit.

Vòng đời Credit

Nếu chưa thể xác minh yêu cầu hoặc việc hoàn Credit, API trả REFUND_PENDING cùng request ID và Retry-After: 30. Giữ nguyên Idempotency-Key và không gửi cùng ảnh bằng khóa mới.

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

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

Tính lũy đẳng và thử lại

Idempotency-Key gắn với chính xác body JSON đã tuần tự hóa, gồm ảnh và mọi field output được cung cấp. Hãy giữ cả byte yêu cầu gốc lẫn khóa.

• Cùng khóa và body giống hệt: có thể thử lại an toàn mà không giữ Credit hoặc gửi yêu cầu xử lý thứ hai.
• Cùng khóa nhưng body thay đổi: 409 IDEMPOTENCY_CONFLICT.
• Cùng khóa sau khi yêu cầu đã kết thúc: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE; kết quả Base64 hoàn tất không được lưu để phát lại.
• Khóa mới: yêu cầu mới có thể giữ thêm Credit.
• Body JSON tương đương về nghĩa vẫn có thể khác nếu khoảng trắng, thứ tự thuộc tính hoặc giá trị mặc định tường minh thay đổi.

Hướng dẫn Retry-After

429 RATE_LIMITED

Chờ 60 giây rồi thử lại đúng body với cùng khóa.

503 REFUND_PENDING

Chờ 30 giây rồi thử lại đúng body với cùng khóa.

503 UPSTREAM_BUSY

Chờ 10 giây. Chỉ dùng khóa mới cho một lần thử mới có chủ ý.

Hết thời gian mạng hoặc API_UNAVAILABLE

Xem kết quả là chưa xác định và giữ body cùng khóa gốc đến khi giải quyết.

Ví dụ

Thay các phần giữ chỗ trên máy chủ. Không bao giờ để lộ API key trong gói trình duyệt công khai.

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

Cấu hình đầu ra phổ biến để bắt đầu

Các cấu hình này chỉ là điểm khởi đầu, không phải bảo đảm tuân thủ vĩnh viễn cho sàn hoặc danh mục. Tên nền tảng chỉ là nhãn, không phải giá trị 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}

Lỗi và khắc phục sự cố

Lỗi dùng trạng thái HTTP ổn định và mã ngắn trong phản hồi JSON.

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

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

Khắc phục sự cố an toàn

1. Ghi lại trạng thái HTTP, mã lỗi, request_id nếu có, thời gian và Idempotency-Key.
2. Không ghi log hoặc gửi Bearer key, toàn bộ image_base64 hay toàn bộ phản hồi chứa dữ liệu ảnh.
3. Sửa lỗi 4xx về yêu cầu, thông tin xác thực, số dư hoặc header trước khi thử lại.
4. Tuân thủ Retry-After và giữ body cùng khóa gốc cho yêu cầu chưa giải quyết.
5. Liên hệ hỗ trợ bằng mã nhận dạng không bí mật nếu trạng thái chưa giải quyết kéo dài.

Giới hạn yêu cầu

Gửi một ảnh JPG, PNG hoặc WebP mỗi yêu cầu dưới dạng Base64 chuẩn. Dữ liệu giải mã tối đa 5 MiB và toàn bộ body JSON tối đa 7.500.000 byte. Đầu ra tùy chỉnh giới hạn 4.096 px mỗi cạnh và 4.194.304 pixel. Nếu kết quả chính xác được yêu cầu không vừa giới hạn phản hồi inline, quá trình thất bại và Credit đã giữ được hoàn; API không bao giờ âm thầm đổi kích thước hoặc định dạng.