เอกสาร API

เริ่มต้นอย่างรวดเร็ว

คำขอแรกต้องมีเพียง input.image_base64 หากไม่ส่ง input.output ระบบจะคืนภาพโปร่งใสขนาดเดิมที่เข้ากันได้กับไคลเอนต์เดิม

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

ยืนยันตัวตนด้วย Bearer key

สร้าง API Key ในบัญชีส่วนตัว แล้วส่งในส่วนหัว Authorization ของทุกคำขอ

Authorization: Bearer rz_live_your_api_key

• เก็บ Key ในตัวแปรสภาพแวดล้อมหรือระบบจัดการความลับของเซิร์ฟเวอร์
• ห้ามใส่ Key ในโค้ดเบราว์เซอร์ แอปมือถือ ส่วนขยาย URL ที่เก็บโค้ดสาธารณะ หรือบันทึก
• แยก Key สำหรับบริการหรือสภาพแวดล้อมต่างกันเมื่อทำได้
• เพิกถอนและเปลี่ยน Key ทันทีหากอาจรั่วไหล

เรียก API จากเซิร์ฟเวอร์ของคุณ

ใช้เส้นทาง เบราว์เซอร์หรือไคลเอนต์ → เซิร์ฟเวอร์ของคุณ → RemoveZero API เนื่องจาก Bearer key อนุญาตงานแบบชำระเงิน ไคลเอนต์สาธารณะจึงเก็บเป็นความลับไม่ได้ คำขอฝั่งเซิร์ฟเวอร์แบบชำระเงินต้องไม่ส่งส่วนหัว Origin

ส่งคำขอลบพื้นหลัง

ส่งคำขอ JSON ที่ตรงตามรูปแบบจากเซิร์ฟเวอร์ ระบบจะตรวจส่วนหัวที่จำเป็นก่อนสำรองเครดิตหรือประมวลผลภาพ

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 ต้องเป็น application/json และใส่ charset ได้
• Content-Encoding ต้องไม่ส่งหรือเป็น identity ระบบปฏิเสธ body ที่บีบอัด
• ห้ามส่งส่วนหัว Origin
• Idempotency-Key ต้องยาว 1–128 ตัว ใช้ตัวอักษร ตัวเลข จุด ขีดล่าง โคลอน หรือขีดกลาง
• image_base64 ต้องเป็นไบต์ภาพ Base64 มาตรฐานโดยไม่มีคำนำหน้า data:image/...

ปรับแต่งผลลัพธ์

input.output เป็นตัวเลือก ใช้เปลี่ยนแคนวาสหลังการลบพื้นหลังครั้งเดิม จึงไม่ใช้เครดิตเพิ่ม

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

ใช้ contain + center แบบคงที่

fit ไม่ใช่ฟิลด์คำขอ RemoveZero จะรักษาอัตราส่วนของตัวแบบและวางทั้งหมดลงในแคนวาสที่มี

• ตัวแบบทั้งหมดมองเห็นได้และอยู่กึ่งกลาง
• ไม่ครอปหรือยืดตัวแบบ
• พื้นที่แคนวาสที่เหลือเป็นโปร่งใสหรือสีที่ขอ
• ไม่รองรับ cover, smart crop, ตำแหน่ง gravity หรือพิกัดอิสระ

รองรับไคลเอนต์เดิม

ไคลเอนต์เดิมสามารถไม่ส่ง input.output และส่งเฉพาะ input.image_base64 เพิ่ม output เมื่อต้องการรูปแบบ พื้นหลัง แคนวาส หรือระยะขอบที่กำหนดเอง

การตอบกลับที่สำเร็จ

ภาพที่สำเร็จคืน HTTP 200 และใช้ 1 เครดิต ผลลัพธ์มี content type ขนาดแคนวาส และข้อมูล Base64 ที่เซิร์ฟเวอร์ถอดรหัสได้

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

ถอดรหัสผลลัพธ์

1. ยืนยัน HTTP 200, ok: true และ status: COMPLETED
2. อ่าน output.content_type และยอมรับเฉพาะ image/png หรือ image/webp
3. ถอดรหัส output.output_base64 หนึ่งครั้ง แล้วบันทึกไบต์ด้วยนามสกุลที่ตรงกัน
4. เมื่อขอขนาด ให้ตรวจ output.width และ output.height

ผลลัพธ์ส่งกลับโดยตรง ไม่ใช่ URL ถาวร หากต้องเก็บหรือส่งต่อภาพ ให้แอปของคุณบันทึกไบต์ที่ถอดรหัสแล้ว

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

การคิดและคืนเครดิต

แต่ละคำขอประมวลผลหนึ่งภาพ RemoveZero ตรวจคำขอ สำรอง 1 เครดิตแบบอะตอม และตัดเครดิตเมื่อทั้งการลบพื้นหลังและผลลัพธ์ที่ขอสำเร็จ การปรับผลลัพธ์ไม่เพิ่มการประมวลผลหรือเครดิต

วงจรเครดิต

หากยังยืนยันคำขอหรือการคืนเครดิตไม่ได้ API จะคืน REFUND_PENDING พร้อม request ID และ Retry-After: 30 โปรดใช้ Idempotency-Key เดิมและอย่าส่งภาพเดิมด้วย Key ใหม่

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

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

Idempotency และการลองใหม่

Idempotency-Key ผูกกับ JSON body ที่ serialize แล้วแบบตรงกันทุกไบต์ รวมทั้งภาพและทุกฟิลด์ output ที่ส่ง โปรดเก็บ body เดิมพร้อม Key

• Key เดิมและ body ตรงกันทุกประการ: ลองใหม่ได้โดยไม่สำรองเครดิตหรือประมวลผลซ้ำ
• Key เดิมแต่ body เปลี่ยน: 409 IDEMPOTENCY_CONFLICT
• ใช้ Key เดิมหลังคำขอจบ: 409 IDEMPOTENCY_REPLAY_UNAVAILABLE เพราะไม่เก็บผล Base64 ไว้ replay
• Key ใหม่: เป็นคำขอใหม่ที่อาจสำรองเครดิตอีกครั้ง
• JSON ที่มีความหมายเท่ากันอาจยังต่างกันหากช่องว่าง ลำดับฟิลด์ หรือค่าเริ่มต้นที่เขียนชัดเจนเปลี่ยน

แนวทาง Retry-After

429 RATE_LIMITED

รอ 60 วินาที แล้วลอง body เดิมด้วย Key เดิม

503 REFUND_PENDING

รอ 30 วินาที แล้วลอง body เดิมด้วย Key เดิม

503 UPSTREAM_BUSY

รอ 10 วินาที ใช้ Key ใหม่เฉพาะเมื่อตั้งใจเริ่มความพยายามใหม่

เครือข่ายหมดเวลาหรือ API_UNAVAILABLE

ถือว่าผลลัพธ์ยังไม่ทราบ และเก็บ body กับ Key เดิมจนกว่าจะยืนยันได้

ตัวอย่าง

แทนที่ placeholder บนเซิร์ฟเวอร์ของคุณ ห้ามเปิดเผย API key ในชุดโค้ดเบราว์เซอร์สาธารณะ

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

จุดเริ่มต้นผลลัพธ์ที่ใช้บ่อย

ตัวอย่างเหล่านี้เป็นจุดเริ่มต้น ไม่ใช่การรับรองว่าจะผ่านกฎของมาร์เก็ตเพลสหรือหมวดหมู่ตลอดไป ชื่อแพลตฟอร์มเป็นเพียงป้าย ไม่ใช่ค่า 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}

ข้อผิดพลาดและการแก้ปัญหา

ข้อผิดพลาดใช้สถานะ HTTP ที่คงที่และรหัสสั้นใน JSON

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

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

แก้ปัญหาอย่างปลอดภัย

1. บันทึกสถานะ HTTP รหัสข้อผิดพลาด request_id ถ้ามี เวลา และ Idempotency-Key
2. ห้ามบันทึกหรือส่ง Bearer key, image_base64 แบบเต็ม หรือ response ที่มีข้อมูลภาพครบ
3. แก้ข้อผิดพลาด 4xx เรื่องคำขอ ข้อมูลรับรอง ยอดเครดิต หรือส่วนหัวก่อนลองใหม่
4. ทำตาม Retry-After และเก็บ body กับ Key เดิมสำหรับคำขอที่ยังไม่ยืนยัน
5. ติดต่อฝ่ายสนับสนุนด้วยตัวระบุที่ไม่เป็นความลับ หากสถานะค้างต่อเนื่อง

ข้อจำกัดคำขอ

ส่งภาพ JPG, PNG หรือ WebP หนึ่งภาพต่อคำขอเป็น Base64 มาตรฐาน อินพุตหลังถอดรหัสสูงสุด 5 MiB และ JSON body ทั้งหมดสูงสุด 7,500,000 ไบต์ ผลลัพธ์กำหนดเองสูงสุด 4,096 พิกเซลต่อด้านและ 4,194,304 พิกเซล หากผลลัพธ์ตามที่ขอไม่พอดีกับขีดจำกัด response แบบ inline งานจะล้มเหลวและคืนเครดิตที่สำรองไว้ API จะไม่เปลี่ยนขนาดหรือรูปแบบโดยไม่แจ้ง