Tài liệu API xóa nền

Gửi ảnh và nhận PNG trong suốt bằng một khóa API.

POSThttps://api.remox.ai/v1.0/removebg

Bắt đầu nhanh

Lưu khóa được cấp trên máy chủ, không công khai trong trình duyệt hoặc ứng dụng. Đổi khóa vẫn giữ danh tính và số dư khách hàng.

REMOX_API_KEY

Dùng JPG, PNG hoặc WebP tĩnh. Đổi kích thước trước khi tải lên; API không tự đổi kích thước.

Ví dụ mã →

Xác thực

Lưu khóa được cấp trên máy chủ, không công khai trong trình duyệt hoặc ứng dụng. Đổi khóa vẫn giữ danh tính và số dư khách hàng.

Trường	Giá trị cho phép
X-API-Key	remox_live_… / remox_test_…
Secret / X-Subuid / X-Platform-User / X-RapidAPI-User	—
image_url / Base64 / shadow / refine	—

Ví dụ mã

cURL

# Set REMOX_API_KEY in your environment first.
curl 'https://api.remox.ai/v1.0/removebg' \
  -H "X-API-Key: $REMOX_API_KEY" \
  -H 'Idempotency-Key: image-0001' \
  -F 'image_file=@/path/to/input.jpg' \
  -F 'size=auto' \
  --max-time 75 --fail-with-body \
  -D response-headers.txt -o remox-result.png
# On non-2xx, the output file contains error JSON, not a PNG.

Dùng JPG, PNG hoặc WebP tĩnh. Đổi kích thước trước khi tải lên; API không tự đổi kích thước.

input.jpg → image/jpeg · PNG → image/png · WebP → image/webp

Tham chiếu yêu cầu

POST /v1.0/removebg · multipart/form-data

Dùng JPG, PNG hoặc WebP tĩnh. Đổi kích thước trước khi tải lên; API không tự đổi kích thước.

Trường	Bắt buộc	Giá trị cho phép
image_file	✓	JPG / PNG / WebP · ≤20 MiB (20 × 1024 × 1024 bytes) · max(width, height) ≤1920 px · min(width, height) ≤1080 px
size	—	auto
response_format	—	image / json
Idempotency-Key	—	8–128 · A–Z a–z 0–9 . _ : -

Phản hồi

200 · PNG

response_format=image · Content-Type: image/png

X-Request-ID · X-Task-ID · X-Idempotency-Key

200 · JSON

response_format=json

{
  "requestId": "req_…",
  "taskId": "task_…",
  "data": {
    "result_url": "https://storage.example/result.png?signature=…&expires=…"
  }
}

data.result_url ≠ result_b64

Hết thời gian và thử lại

Sau 60 giây, 504 có thể nghĩa là tác vụ vẫn chạy. Kiểm tra trạng thái hoặc thử lại với cùng ảnh và Idempotency-Key để tránh tính phí hai lần.

GET /v1.0/tasks/{taskId}

{
  "requestId": "req_…",
  "taskId": "task_…",
  "status": "completed",
  "progress": null,
  "pollAfterMs": 2000,
  "result": {
    "downloadPath": "/v1.0/tasks/task_…/result",
    "mimeType": "image/png",
    "expiresAt": "2026-10-17T00:00:00.000Z"
  }
}

GET /v1.0/tasks/{taskId}/result
GET /v1.0/tasks/{taskId}/result?response_format=json

creating → queued → processing → completed / failed / timed_out

Retry-After · pollAfterMs: 2000 · X-API-Key

Tài khoản và tín dụng

Tín dụng được giữ khi tạo, trừ khi thành công và trả khi thất bại hoặc tác vụ hết hạn. Hết thời gian đồng bộ không tự trả tín dụng.

Trường	Giá trị cho phép
credits	available / reserved / consumed
GET /v1.0/account	X-API-Key
POST → AI	300 ms
POST → 504	60 s
task → timed_out	35 min
task_expired	90 d
result_expired (Worker)	7 d

Lỗi

Kiểm tra errors và trạng thái trước khi thử lại. Giữ requestId để hỗ trợ; không ghi khóa vào nhật ký.

{
  "requestId": "req_…",
  "retryable": false,
  "errors": [
    {
      "code": "invalid_credentials",
      "title": "Invalid API key."
    }
  ]
}

HTTP	errors[].code	Lỗi
400	invalid_request, invalid_file	Yêu cầu không hợp lệ
400	invalid_size, invalid_response_format	Yêu cầu không hợp lệ
400	invalid_idempotency_key, invalid_subject	Yêu cầu không hợp lệ
402	insufficient_credits	Không đủ tín dụng
403	invalid_credentials	Truy cập bị từ chối
403	platform_disabled, platform_paused, scope_denied	Truy cập bị từ chối
404	not_found, upload_not_found	Không tìm thấy
409	idempotency_conflict	Xung đột hoặc tác vụ chưa xong
409	result_not_ready	Xung đột hoặc tác vụ chưa xong
410	task_expired, result_expired	Đã hết hạn
413	file_too_large	Tệp quá lớn
415	invalid_image, animated_image_unsupported	Ảnh không được hỗ trợ
422	image_dimensions_exceeded	Vượt kích thước
429	rate_limit_exceeded, hourly_quota_exhausted, inflight_limit_exceeded	Vượt giới hạn yêu cầu
502	upload_failed, upstream_rejected, upstream_unavailable	Lỗi dịch vụ nguồn
502	create_result_unknown, remote_service_error, invalid_result, result_unavailable, task_failed, task_timeout	Lỗi dịch vụ nguồn
503	service_not_configured, credit_price_not_configured, server_error	Dịch vụ không khả dụng
504	sync_timeout	Hết thời gian đồng bộ

retryable: 429 / 5xx

Sau 60 giây, 504 có thể nghĩa là tác vụ vẫn chạy. Kiểm tra trạng thái hoặc thử lại với cùng ảnh và Idempotency-Key để tránh tính phí hai lần.

Tương thích

Chỉ xóa nền bằng khóa đơn. Không hỗ trợ toàn bộ tùy chọn remove.bg. URL kết quả JSON là phần mở rộng REMOX.

Đăng ký API →