📚 Tài liệu REST API

Bắt đầu nhanh

1. Đăng ký tài khoản tại Dashboard — hệ thống cấp ngay 1 API key (gói Free, 50 credits).
2. Copy API key (dạng rbg_...) — key chỉ hiển thị một lần, hãy lưu ngay.
3. Gửi ảnh tới endpoint POST /v1/remove-background với header X-API-Key.

Xác thực

Mọi request tới /v1/* đều yêu cầu header X-API-Key:

curl "http://localhost:8000/v1/account/credits" \
  -H "X-API-Key: rbg_your_api_key_here"

import requests

headers = {"X-API-Key": "rbg_your_api_key_here"}
response = requests.get("http://localhost:8000/v1/account/credits", headers=headers)
print(response.json())

Key được lưu trong DB dạng SHA256 hash — nếu làm mất, hãy thu hồi key cũ và tạo key mới trong Dashboard.

Gói dịch vụ & giới hạn

Mỗi lần tách nền thành công trừ 1 credit. Khi hết credit, API trả về mã 402.

POST /v1/remove-background

Tách nền từ file ảnh upload. Body dạng multipart/form-data.

Tham số

Ví dụ

curl -X POST "http://localhost:8000/v1/remove-background" \
  -H "X-API-Key: rbg_your_api_key_here" \
  -F "image=@photo.jpg" \
  -F "return_format=png" \
  -F "size=auto" \
  -F "model=high" \
  -F "alpha_matting=true"

import requests

url = "http://localhost:8000/v1/remove-background"
headers = {"X-API-Key": "rbg_your_api_key_here"}
files = {"image": open("photo.jpg", "rb")}
data = {"return_format": "png", "size": "auto"}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
print(result["data"]["image_url"])

const form = new FormData();
form.append("image", fileInput.files[0]);
form.append("return_format", "png");

const res = await fetch("http://localhost:8000/v1/remove-background", {
  method: "POST",
  headers: { "X-API-Key": "rbg_your_api_key_here" },
  body: form,
});
const result = await res.json();
console.log(result.data.image_url);

<?php
$ch = curl_init('http://localhost:8000/v1/remove-background');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: rbg_your_api_key_here'],
    CURLOPT_POSTFIELDS     => [
        'image'         => new CURLFile('photo.jpg'),
        'return_format' => 'png',
    ],
]);
echo curl_exec($ch);

Response 200

{
  "success": true,
  "data": {
    "image_url": "http://localhost:8000/results/9f2c7a4e....png",
    "base64": null,
    "credits_used": 1,
    "credits_remaining": 99,
    "processing_time": "1.2s",
    "image_size": "1920x1080"
  },
  "message": "Background removed successfully"
}

Với return_format=base64, trường base64 chứa dữ liệu ảnh mã hóa base64 (kèm image_url như thường).

POST /v1/remove-background-url

Tách nền từ URL ảnh công khai. Body dạng JSON.

curl -X POST "http://localhost:8000/v1/remove-background-url" \
  -H "X-API-Key: rbg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg", "size": "auto", "model": "high", "alpha_matting": true}'

import requests

url = "http://localhost:8000/v1/remove-background-url"
headers = {
    "X-API-Key": "rbg_your_api_key_here",
    "Content-Type": "application/json",
}
payload = {"image_url": "https://example.com/photo.jpg"}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response 200

{
  "success": true,
  "data": {
    "image_url": "http://localhost:8000/results/3ab19d0e....png",
    "base64": null,
    "credits_used": 1,
    "credits_remaining": 98,
    "processing_time": "1.4s",
    "image_size": "1600x1200"
  },
  "message": "Background removed successfully"
}

Server chặn URL trỏ tới địa chỉ nội bộ/private (SSRF) và ảnh lớn hơn 10MB.

GET /v1/account/credits

Kiểm tra số credits còn lại của API key.

curl "http://localhost:8000/v1/account/credits" \
  -H "X-API-Key: rbg_your_api_key_here"

Response 200

{
  "success": true,
  "data": {
    "total_credits": 100,
    "used_credits": 25,
    "remaining_credits": 75,
    "plan": "free"
  },
  "message": "OK"
}

GET /v1/account/usage

Lịch sử sử dụng API của key, hỗ trợ phân trang và lọc theo ngày.

curl "http://localhost:8000/v1/account/usage?page=1&limit=20&date_from=2026-01-01" \
  -H "X-API-Key: rbg_your_api_key_here"

Response 200

{
  "success": true,
  "data": {
    "usage": [
      {
        "id": "req_9f2c7a4e5b1d4c3a8e7f2b1d0a9c8e7f",
        "endpoint": "/v1/remove-background",
        "timestamp": "2026-01-15T10:30:00Z",
        "credits_used": 1,
        "image_size": "1920x1080",
        "status": "success",
        "processing_time": 1.21
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 20
  },
  "message": "OK"
}

Mã lỗi

Dạng lỗi chung

{ "success": false, "error": "Invalid API key" }

Lưu ý quan trọng

• Ảnh gốc không được lưu trữ; chỉ ảnh kết quả được giữ và tự xóa sau 24 giờ.
• Kết quả tải được qua image_url hoặc header download /download/{filename}.
• Ảnh nền trong suốt luôn ở định dạng PNG. JPG sẽ tự ghép nền màu (mặc định trắng).
• Vượt rate limit sẽ nhận mã 429 kèm header Retry-After — hãy retry sau khoảng thời gian đó.