---
description: "เอกสารอ้างอิง REST API ฉบับสมบูรณ์ เอนด์พอยต์ของเครื่องมือ การประมวลผลแบบแบตช์ ไปป์ไลน์ คลังไฟล์ การยืนยันตัวตน ทีม และการดำเนินงานของผู้ดูแลระบบ"
i18n_output_hash: 34c52fe6305e
i18n_source_hash: 7e0a0db4abe0
i18n_provenance: human
---

# เอกสารอ้างอิง REST API {#rest-api-reference}

เอกสาร API แบบโต้ตอบพร้อมตัวอย่างคำขอและการตอบกลับมีให้ใช้งานที่ [http://localhost:1349/api/docs](http://localhost:1349/api/docs)

สเปกแบบเครื่องอ่านได้:
- `/api/v1/openapi.yaml` - สเปก OpenAPI 3.1
- `/llms.txt` - สรุปที่เป็นมิตรกับ LLM
- `/llms-full.txt` - เอกสารฉบับสมบูรณ์ที่เป็นมิตรกับ LLM

## การยืนยันตัวตน {#authentication}

ทุกเอนด์พอยต์ต้องมีการยืนยันตัวตน เว้นแต่ `AUTH_ENABLED=false`

### โทเคนเซสชัน {#session-token}

```bash
# Login
curl -X POST http://localhost:1349/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# Returns: {"token":"<session-token>"}

# Use token (tool routes are POST multipart)
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

เซสชันจะหมดอายุหลังจาก 7 วัน (กำหนดค่าได้ผ่าน `SESSION_DURATION_HOURS`)

### API Keys {#api-keys}

```bash
# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

# Use the key
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

คีย์จะมีคำนำหน้า `si_` และจัดเก็บเป็นแฮชแบบ scrypt คีย์ดิบจะแสดงเพียงครั้งเดียวและไม่สามารถเรียกคืนได้อีก

### เอนด์พอยต์การยืนยันตัวตน {#auth-endpoints}

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `POST` | `/api/auth/login` | สาธารณะ | ลงชื่อเข้าใช้ รับโทเคนเซสชัน |
| `POST` | `/api/auth/logout` | ยืนยันตัวตน | ทำลายเซสชันปัจจุบัน |
| `GET` | `/api/auth/session` | ยืนยันตัวตน | ตรวจสอบเซสชันปัจจุบัน |
| `POST` | `/api/auth/change-password` | ยืนยันตัวตน | เปลี่ยนรหัสผ่านของตนเอง (ทำให้เซสชันอื่นทั้งหมด + API keys ใช้ไม่ได้) |
| `GET` | `/api/auth/users` | ผู้ดูแลระบบ | แสดงรายชื่อผู้ใช้ทั้งหมด |
| `POST` | `/api/auth/register` | ผู้ดูแลระบบ | สร้างผู้ใช้ใหม่ |
| `PUT` | `/api/auth/users/:id` | ผู้ดูแลระบบ | อัปเดตบทบาทหรือทีมของผู้ใช้ |
| `POST` | `/api/auth/users/:id/reset-password` | ผู้ดูแลระบบ | รีเซ็ตรหัสผ่านของผู้ใช้ |
| `DELETE` | `/api/auth/users/:id` | ผู้ดูแลระบบ | ลบผู้ใช้ |
| `GET` | `/api/v1/config/auth` | สาธารณะ | ตรวจสอบว่าเปิดใช้งานการยืนยันตัวตนอยู่หรือไม่ (`{ authEnabled: bool }`) |
| `POST` | `/api/auth/mfa/enroll` | ยืนยันตัวตน | เริ่มการลงทะเบียน TOTP MFA ต้องใช้ฟีเจอร์ `mfa` ระดับ enterprise |
| `POST` | `/api/auth/mfa/verify` | ยืนยันตัวตน | ยืนยันการลงทะเบียน MFA ด้วยรหัส TOTP |
| `POST` | `/api/auth/mfa/complete` | สาธารณะ | ทำ MFA login challenge ที่ค้างอยู่ให้เสร็จสมบูรณ์ |
| `POST` | `/api/auth/mfa/disable` | ยืนยันตัวตน | ปิดใช้งาน MFA สำหรับผู้ใช้ปัจจุบัน |
| `POST` | `/api/auth/users/:id/mfa/reset` | ผู้ดูแลระบบ (`users:manage`) | รีเซ็ต MFA สำหรับผู้ใช้ |
| `GET` | `/api/auth/oidc/login` | สาธารณะ | เริ่มการลงชื่อเข้าใช้ OIDC เมื่อเปิดใช้งาน OIDC |
| `GET` | `/api/auth/oidc/callback` | สาธารณะ | callback การอนุญาตของ OIDC |
| `GET` | `/api/auth/saml/metadata` | สาธารณะ | XML เมทาดาทา SAML SP เมื่อเปิดใช้งาน SAML |
| `GET` | `/api/auth/saml/login` | สาธารณะ | เริ่มการลงชื่อเข้าใช้ SAML |
| `POST` | `/api/auth/saml/callback` | สาธารณะ | บริการ SAML assertion consumer |

เมื่อเปิดใช้งาน MFA สำหรับผู้ใช้ `POST /api/auth/login` จะคืนค่า `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` แทนโทเคนเซสชัน ส่ง `mfaToken` นั้นพร้อมรหัส TOTP หรือรหัสกู้คืนไปยัง `/api/auth/mfa/complete`

### สิทธิ์ {#permissions}

| สิทธิ์ | ผู้ดูแลระบบ | ผู้ใช้ |
|-----------|:-----:|:----:|
| ใช้เครื่องมือ | ✓ | ✓ |
| ไฟล์/ไปป์ไลน์/API keys ของตนเอง | ✓ | ✓ |
| ดูไฟล์/ไปป์ไลน์/คีย์ของผู้ใช้ทุกคน | ✓ | - |
| เขียนการตั้งค่า | ✓ | - |
| จัดการผู้ใช้และทีม | ✓ | - |
| จัดการแบรนด์ | ✓ | - |

## การตรวจสอบสถานะ {#health-check}

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | สาธารณะ | การตรวจสอบสถานะพื้นฐาน คืนค่า `{"status":"healthy","version":"..."}` พร้อม 200 หรือ `{"status":"unhealthy"}` พร้อม 503 หากไม่สามารถเข้าถึงฐานข้อมูลได้ |
| `GET` | `/api/v1/readyz` | สาธารณะ | Readiness probe ตรวจสอบ PostgreSQL, Redis, พื้นที่ดิสก์ และ S3 เมื่อมีการกำหนดค่า คืนค่า 503 เมื่ออินสแตนซ์ไม่ควรรับทราฟฟิก |
| `GET` | `/api/v1/admin/health` | ผู้ดูแลระบบ (`system:health`) | การวินิจฉัยแบบละเอียด รวมถึง uptime, โหมดการจัดเก็บ, สถานะฐานข้อมูล, สถานะคิว และความพร้อมใช้งานของ GPU |

## การใช้เครื่องมือ {#using-tools}

ทุกเครื่องมือใช้รูปแบบเดียวกัน:

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'

# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'settings={...}'
```

`<section>` เป็นหนึ่งใน `image`, `video`, `audio`, `pdf` หรือ `files`

- การอัปโหลดคือ `multipart/form-data`
- `settings` เป็นสตริง JSON ที่มีตัวเลือกเฉพาะของเครื่องมือ
- `clientJobId` เป็นฟิลด์ฟอร์มที่ไม่บังคับสำหรับการเชื่อมโยงความคืบหน้าที่ผู้เรียกจัดเตรียมให้
- `fileId` เป็นฟิลด์ฟอร์มที่ไม่บังคับซึ่งอ้างอิงถึงรายการในคลังไฟล์ที่มีอยู่ เมื่อมีค่านี้ ผลลัพธ์ที่ประมวลผลแล้วจะถูกบันทึกเป็นเวอร์ชันใหม่ และการตอบกลับจะรวม `savedFileId`
- **เครื่องมือแบบเร็ว** โดยทั่วไปจะคืนค่า 200 JSON: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}` ดึงไฟล์ที่ประมวลผลแล้วจาก `downloadUrl`
- **เครื่องมือที่เข้าคิวใดๆ** สามารถคืนค่า 202 JSON ได้หากทำงานนานหรือเกินหน้าต่างการรอแบบซิงโครนัส: `{"jobId":"...","async":true}` เชื่อมต่อกับ SSE เพื่อรับความคืบหน้า แล้วดาวน์โหลดเมื่อเสร็จสมบูรณ์ (ดู [การติดตามความคืบหน้า](#progress-tracking))
- **แบตช์** เส้นทางจะคืนค่าไฟล์บีบอัด ZIP แบบสตรีมโดยตรง (พร้อมส่วนหัว `X-Job-Id`) สำหรับเครื่องมือที่ลงทะเบียนใน generic batch registry

## เอกสารอ้างอิงเครื่องมือ {#tools-reference}

### พรีเซ็ตการแปลง {#conversion-presets}

แคตตาล็อกที่ใช้ร่วมกันมีเอนด์พอยต์พรีเซ็ตการแปลงเฉพาะ 83 รายการ เช่น `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` และ `excel-to-csv` พรีเซ็ตเป็นเส้นทางเครื่องมือระดับหนึ่ง:

`POST /api/v1/tools/<section>/<presetId>`

แต่ละพรีเซ็ตล็อกรูปแบบเอาต์พุตและมอบหมายให้เครื่องมือฐาน เช่น `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` หรือ `convert-spreadsheet` ดู [พรีเซ็ตการแปลง](/th/tools/conversion-presets) สำหรับตารางเส้นทางฉบับสมบูรณ์และการตั้งค่าที่ไม่บังคับ

### พื้นฐาน {#essentials}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `resize` | ปรับขนาด | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement` พร้อมพรีเซ็ตโซเชียลมีเดีย 23 รายการ |
| `crop` | ครอป | `left`, `top`, `width`, `height`, `unit` (px/percent) |
| `rotate` | หมุนและพลิก | `angle`, `horizontal` (bool), `vertical` (bool) |
| `convert` | แปลง | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
| `compress` | บีบอัด | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |

### การปรับปรุงประสิทธิภาพ {#optimization}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `optimize-for-web` | ปรับให้เหมาะกับเว็บ | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
| `strip-metadata` | ลบเมทาดาทา | - |
| `edit-metadata` | แก้ไขเมทาดาทา | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
| `bulk-rename` | เปลี่ยนชื่อแบบกลุ่ม | `pattern` (รองรับ `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
| `image-to-pdf` | รูปภาพเป็น PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
| `favicon` | ตัวสร้าง Favicon | `padding`, `backgroundColor`, `borderRadius` - สร้างขนาดมาตรฐานทั้งหมด |

### การปรับแต่ง {#adjustments}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `adjust-colors` | ปรับสี | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
| `sharpening` | การทำให้คมชัด | `method` (adaptive/unsharp-mask/high-pass), `sigma`, `m1`, `m2`, `x1`, `y2`, `y3`, `amount`, `radius`, `threshold`, `strength`, `kernelSize` (3/5), `denoise` (off/light/medium/strong) |
| `replace-color` | แทนที่สี | `sourceColor`, `targetColor` (สีที่ใช้แทน), `makeTransparent`, `tolerance` |
| `color-blindness` | จำลองภาวะตาบอดสี | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, ค่าเริ่มต้น "deuteranomaly") |
| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
| `pixelate` | Pixelate | `blockSize` (2-128), `region` ({left, top, width, height} สำหรับการทำ pixelation บางส่วน) |
| `vignette` | Vignette | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |

### เครื่องมือ AI {#ai-tools}

เครื่องมือ AI ทั้งหมดทำงานบนฮาร์ดแวร์ของคุณ: CPU โดยค่าเริ่มต้น หรือ NVIDIA CUDA เมื่อมี NVIDIA GPU ที่รองรับ การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน ไม่ต้องใช้อินเทอร์เน็ต

| Tool ID | ชื่อ | โมเดล AI | การตั้งค่าหลัก |
|---------|------|---------|-------------|
| `remove-background` | ลบพื้นหลัง | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
| `upscale` | ขยายภาพ | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
| `erase-object` | ลบวัตถุ | LaMa (ONNX) | ส่ง Mask เป็นส่วนไฟล์ที่สอง (fieldname `mask`), `format`, `quality` |
| `ocr` | OCR / การแยกข้อความ | Tesseract (เร็ว); RapidOCR + PP-OCR ONNX (สมดุล/ดีที่สุด) | `quality` (เร็ว/สมดุล/ดีที่สุด), `language`, `enhance` |
| `blur-faces` | เบลอใบหน้า / PII | MediaPipe | `blurRadius`, `sensitivity` |
| `smart-crop` | ครอปอัจฉริยะ | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
| `image-enhancement` | เพิ่มคุณภาพภาพ | อิงจากการวิเคราะห์ | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
| `enhance-faces` | เพิ่มคุณภาพใบหน้า | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
| `colorize` | ลงสีด้วย AI | DDColor | `intensity`, `model` |
| `noise-removal` | ลบสัญญาณรบกวน | การลดสัญญาณรบกวนแบบหลายระดับ | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
| `red-eye-removal` | ลบตาแดง | Face landmark + การวิเคราะห์สี | `sensitivity`, `strength` |
| `restore-photo` | ฟื้นฟูภาพถ่าย | ไปป์ไลน์หลายขั้นตอน | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
| `passport-photo` | รูปถ่ายพาสปอร์ต | MediaPipe landmarks | โฟลว์แบบสองขั้นตอน การวิเคราะห์ใช้ multipart `file`; การสร้างใช้ JSON พร้อม `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), landmarks, มิติภาพ |
| `content-aware-resize` | ปรับขนาดแบบรับรู้เนื้อหา | Seam carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
| `transparency-fixer` | ตัวแก้ความโปร่งใส PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
| `background-replace` | แทนที่พื้นหลัง | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
| `blur-background` | เบลอพื้นหลัง | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
| `ai-canvas-expand` | ขยายผืนผ้าใบด้วย AI | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |

### ลายน้ำและการซ้อนทับ {#watermark-overlay}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `watermark-text` | ลายน้ำข้อความ | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
| `watermark-image` | ลายน้ำรูปภาพ | `opacity`, `position`, `scale` - ไฟล์ที่สองคือลายน้ำ |
| `text-overlay` | ซ้อนทับข้อความ | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
| `compose` | การประกอบภาพ | `x`, `y`, `opacity`, `blend` - ไฟล์ที่สองถูกวางเป็นเลเยอร์ด้านบน |
| `meme-generator` | ตัวสร้างมีม | `templateId`, `textLayout` (top-bottom/top-only/bottom-only/center/side-by-side), `textBoxes` ([{id, text}]), `fontFamily` (anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto), `fontSize`, `textColor`, `strokeColor`, `textAlign`, `allCaps` รองรับโหมดเทมเพลต (JSON body พร้อม `templateId`) หรือโหมดรูปภาพกำหนดเอง (multipart พร้อมไฟล์) |

### ยูทิลิตี {#utilities}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `info` | ข้อมูลรูปภาพ | - (คืนค่า width, height, format, size, channels, hasAlpha, DPI, EXIF) |
| `compare` | เปรียบเทียบรูปภาพ | `mode` (side-by-side/overlay/diff), `diffThreshold` - ไฟล์ที่สองคือเป้าหมายการเปรียบเทียบ |
| `find-duplicates` | ค้นหารูปซ้ำ | `threshold` (ระยะห่างของ perceptual hash, ค่าเริ่มต้น 8) - หลายไฟล์ |
| `color-palette` | จานสี | `count` (จำนวนสีเด่น), `format` (hex/rgb) |
| `qr-generate` | ตัวสร้าง QR Code | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (ไฟล์ที่ไม่บังคับ) |
| `barcode-read` | ตัวอ่านบาร์โค้ด | - (ตรวจจับ QR, EAN, Code128, DataMatrix ฯลฯ โดยอัตโนมัติ) |
| `image-to-base64` | รูปภาพเป็น Base64 | `format` (data-uri/plain), `mimeType` |
| `html-to-image` | HTML เป็นรูปภาพ | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
| `histogram` | ฮิสโทแกรม | `scale` (linear/log) - คืนค่าแผนภูมิฮิสโทแกรม RGB + สถิติต่อแชนเนล |
| `lqip-placeholder` | LQIP Placeholder | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
| `barcode-generate` | ตัวสร้างบาร์โค้ด | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool) JSON body ไม่มีการอัปโหลดไฟล์ |

### เลย์เอาต์และการประกอบภาพ {#layout-composition}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `collage` | คอลลาจ / ตาราง | `template` (เลย์เอาต์ 25+ แบบ), `gap`, `backgroundColor`, `borderRadius` - หลายไฟล์ |
| `stitch` | เย็บ / รวมภาพ | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - หลายไฟล์ |
| `split` | แยกรูปภาพ | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
| `border` | ขอบและกรอบ | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
| `beautify` | ตกแต่งภาพหน้าจอ | `backgroundType` (solid/linear-gradient/radial-gradient/image/transparent), `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame` (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), `socialPreset` (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), `watermarkText`, `outputFormat` |
| `circle-crop` | ครอปวงกลม | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
| `image-pad` | เติมขอบรูปภาพ | `target` (16:9/9:16/1:1/4:3/3:4/custom), `ratioW`, `ratioH`, `background` (color/transparent/blur), `color` (hex), `padding` (0-50%) |
| `sprite-sheet` | Sprite Sheet | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - หลายไฟล์ (2-64 รูป) |

### รูปแบบและการแปลง {#format-conversion}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `svg-to-raster` | SVG เป็นแรสเตอร์ | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
| `vectorize` | รูปภาพเป็น SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
| `gif-tools` | เครื่องมือ GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), พารามิเตอร์เฉพาะแอ็กชัน |
| `gif-webp` | ตัวแปลง GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |

### เครื่องมือวิดีโอ {#video-tools}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `convert-video` | แปลงวิดีโอ | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
| `compress-video` | บีบอัดวิดีโอ | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
| `trim-video` | ตัดวิดีโอ | `startS`, `endS`, `precise` (bool, ตัดแบบแม่นยำระดับเฟรม) |
| `mute-video` | ปิดเสียงวิดีโอ | - |
| `video-to-gif` | วิดีโอเป็น GIF | `fps` (1-30), `width`, `startS`, `durationS` (สูงสุด 60 วินาที) |
| `resize-video` | ปรับขนาดวิดีโอ | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
| `crop-video` | ครอปวิดีโอ | `width`, `height`, `x`, `y` |
| `rotate-video` | หมุนวิดีโอ | `transform` (cw90/ccw90/180/hflip/vflip) |
| `change-fps` | เปลี่ยน FPS | `fps` (1-120) |
| `video-color` | สีวิดีโอ | `brightness`, `contrast`, `saturation`, `gamma` |
| `video-speed` | ความเร็ววิดีโอ | `factor` (0.25-4), `keepPitch` (bool) |
| `reverse-video` | ย้อนวิดีโอ | - (สูงสุด 5 นาที) |
| `video-loudnorm` | ปรับระดับเสียงให้เท่ากัน | - (EBU R128) |
| `aspect-pad` | เติมขอบตามอัตราส่วน | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
| `blur-pad` | เติมขอบด้วยความเบลอ | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
| `watermark-video` | ลายน้ำวิดีโอ | `text`, `position`, `fontSize`, `opacity`, `color` |
| `stabilize-video` | ทำวิดีโอให้นิ่ง | `smoothing` (5-60, เป็นเฟรม) |
| `gif-to-video` | GIF เป็นวิดีโอ | `format` (mp4/webm/mov) |
| `video-to-webp` | วิดีโอเป็น WebP | `fps`, `width`, `quality`, `loop` (bool) |
| `video-to-frames` | วิดีโอเป็นเฟรม | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
| `merge-videos` | รวมวิดีโอ | - (หลายไฟล์ ปรับเป็นความละเอียดของวิดีโอแรก) |
| `replace-audio` | แทนที่เสียง | - (วิดีโอ + ไฟล์เสียง สองไฟล์) |
| `burn-subtitles` | ฝังคำบรรยาย (Burn) | `fontSize` (8-72) - วิดีโอ + ไฟล์คำบรรยาย |
| `embed-subtitles` | ฝังคำบรรยาย (Embed) | `language` (รหัส ISO 639-2/B) - วิดีโอ + ไฟล์คำบรรยาย |
| `extract-subtitles` | สกัดคำบรรยาย | - (ส่งออก SRT) |
| `images-to-video` | รูปภาพเป็นวิดีโอ | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - หลายไฟล์ |
| `video-metadata` | ล้างเมทาดาทาวิดีโอ | - |
| `auto-subtitles` | คำบรรยายอัตโนมัติ (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
| `extract-audio` | สกัดเสียง | `format` (mp3/wav/m4a/ogg) |

### เครื่องมือเสียง {#audio-tools}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `convert-audio` | แปลงเสียง | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
| `trim-audio` | ตัดเสียง | `startS`, `endS` |
| `volume-adjust` | ปรับระดับเสียง | `gainDb` (-30 ถึง 30) |
| `normalize-audio` | ปรับระดับเสียงให้เท่ากัน | - (EBU R128, -16 LUFS) |
| `fade-audio` | เฟดเสียง | `fadeInS` (0-30), `fadeOutS` (0-30) |
| `reverse-audio` | ย้อนเสียง | - |
| `audio-speed` | ความเร็วเสียง | `factor` (0.25-4) |
| `pitch-shift` | เปลี่ยนระดับเสียง (Pitch) | `semitones` (-12 ถึง 12) |
| `audio-channels` | ช่องสัญญาณเสียง | `mode` (stereo-to-mono/mono-to-stereo/swap) |
| `silence-removal` | ลบความเงียบ | `thresholdDb` (-80 ถึง -20), `minSilenceS` (0.1-5) |
| `noise-reduction` | ลดสัญญาณรบกวน | `strength` (light/medium/strong) |
| `merge-audio` | รวมเสียง | `format` (mp3/wav/flac/m4a) - หลายไฟล์ |
| `split-audio` | แยกเสียง | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
| `ringtone-maker` | ตัวสร้างริงโทน | `startS`, `durationS` (1-30) |
| `waveform-image` | รูปภาพเวฟฟอร์ม | `width`, `height`, `color` (hex) |
| `audio-metadata` | เมทาดาทาเสียง | `strip` (bool), `title`, `artist`, `album` |
| `transcribe-audio` | ถอดเสียงเป็นข้อความ (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |

### เครื่องมือเอกสาร {#document-tools}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `merge-pdf` | รวม PDF | - (หลายไฟล์ สูงสุด 20 PDF) |
| `split-pdf` | แยก PDF | `mode` (range/every), `range`, `everyN` (1-500) |
| `compress-pdf` | บีบอัด PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
| `rotate-pdf` | หมุน PDF | `angle` (90/180/270), `range` (ช่วงหน้า) |
| `extract-pages` | สกัดหน้า | `range` (ไวยากรณ์ qpdf เช่น "1-5,8,10-z") |
| `remove-pages` | ลบหน้า | `pages` (ช่วง qpdf ที่จะลบ) |
| `organize-pdf` | จัดระเบียบ PDF | `order` (ลำดับหน้า qpdf เช่น "3,1,2,5-z") |
| `protect-pdf` | ป้องกัน PDF | `userPassword`, `ownerPassword` (AES-256) |
| `unlock-pdf` | ปลดล็อก PDF | `password` |
| `repair-pdf` | ซ่อมแซม PDF | - |
| `linearize-pdf` | ปรับ PDF ให้เหมาะกับเว็บ | - (linearize เพื่อการดูบนเว็บที่รวดเร็ว) |
| `grayscale-pdf` | PDF ระดับสีเทา | - |
| `pdfa-convert` | แปลงเป็น PDF/A | - (PDF/A-2 สำหรับการเก็บถาวร) |
| `crop-pdf` | ครอป PDF | `margin` (0-2000 จุด) |
| `nup-pdf` | N-up PDF | `perSheet` (2/3/4/8/9/12/16) |
| `booklet-pdf` | สมุดพับ PDF | `perSheet` (2/4/6/8) |
| `watermark-pdf` | ลายน้ำ PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
| `pdf-page-numbers` | เลขหน้า PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
| `flatten-pdf` | Flatten PDF | - (ทำให้ฟอร์มและคำอธิบายประกอบกลายเป็นภาพ) |
| `redact-pdf` | ปกปิดข้อมูล PDF | `terms` (string[]), `caseSensitive` (bool) |
| `sign-pdf` | ลงนาม PDF | เส้นทาง multipart กำหนดเองพร้อม PDF `file`, ไฟล์ลายเซ็น `sig0`, `sig1` และอาร์เรย์ JSON `placements` |
| `pdf-to-text` | PDF เป็นข้อความ | - |
| `pdf-to-word` | PDF เป็น Word | - |
| `pdf-metadata` | เมทาดาทา PDF | `title`, `author`, `subject`, `keywords` |
| `convert-document` | แปลงเอกสาร | `format` (docx/odt/rtf/txt) |
| `convert-presentation` | แปลงงานนำเสนอ | `format` (pptx/odp) |
| `convert-spreadsheet` | แปลงสเปรดชีต | `format` (xlsx/ods/csv) |
| `excel-to-pdf` | Excel เป็น PDF | - |
| `word-to-pdf` | Word เป็น PDF | - |
| `powerpoint-to-pdf` | PowerPoint เป็น PDF | - |
| `html-to-pdf` | HTML เป็น PDF | - (ปิดใช้งานทรัพยากรระยะไกล) |
| `markdown-to-docx` | Markdown เป็น Word | - |
| `markdown-to-html` | Markdown เป็น HTML | - |
| `markdown-to-pdf` | Markdown เป็น PDF | - (ปิดใช้งานทรัพยากรระยะไกล) |
| `epub-convert` | แปลง EPUB | `format` (pdf/docx/html/md) |
| `to-epub` | แปลงเป็น EPUB | - (รับ .docx, .md, .html, .txt) |
| `ocr-pdf` | PDF OCR (AI) | `quality` (fast/balanced/best), `language` (auto/en/de/fr/es/zh/ja/ko), `pages` |
| `pdf-to-image` | PDF เป็นรูปภาพ | `pages` (all/range), `format`, `dpi`, `quality` |
| `pdf-to-jpg` | PDF เป็น JPG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-png` | PDF เป็น PNG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-tiff` | PDF เป็น TIFF | `pages`, `dpi`, `quality`, `colorMode` |

### เครื่องมือไฟล์ {#file-tools}

| Tool ID | ชื่อ | การตั้งค่าหลัก |
|---------|------|-------------|
| `chart-maker` | ตัวสร้างแผนภูมิ | `kind` (bar/line/pie), `title`, `width`, `height` |
| `csv-excel` | CSV เป็น Excel | `sheet` (หมายเลขเวิร์กชีตสำหรับอินพุต XLSX) - แบบสองทิศทาง |
| `csv-json` | CSV เป็น JSON | `pretty` (bool) - แบบสองทิศทาง |
| `json-xml` | JSON เป็น XML | `pretty` (bool) - แบบสองทิศทาง |
| `split-csv` | แยก CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
| `merge-csvs` | รวม CSV | - (หลายไฟล์ คอลัมน์ตรงกัน) |
| `yaml-json` | YAML / JSON | - (แบบสองทิศทาง) |
| `xml-to-csv` | XML เป็น CSV | - (ค้นหาองค์ประกอบที่ซ้ำโดยอัตโนมัติ) |
| `excel-to-csv` | Excel เป็น CSV | พรีเซ็ตการแปลงเฉพาะที่รองรับโดย `convert-spreadsheet` |
| `create-zip` | สร้าง ZIP | - (หลายไฟล์ 2-50 ไฟล์) |
| `extract-zip` | แตก ZIP | - (ป้องกัน bomb) |

### HTML เป็นรูปภาพ {#html-to-image}

จับภาพหน้าเว็บเป็นรูปภาพ ต่างจากเครื่องมืออื่น เอนด์พอยต์นี้รับ `application/json` แทน multipart form data (ไม่ต้องอัปโหลดไฟล์)

**เอนด์พอยต์:** `POST /api/v1/tools/image/html-to-image`

**Content-Type:** `application/json`

| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `url` | string | (จำเป็น) | URL ที่จะจับภาพ (http/https เท่านั้น) |
| `format` | string | `"png"` | รูปแบบเอาต์พุต: `jpg`, `png`, `webp` |
| `quality` | number | `90` | คุณภาพ 1-100 (JPG/WebP เท่านั้น) |
| `fullPage` | boolean | `false` | จับภาพทั้งหน้าที่เลื่อนได้ |
| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
| `viewportWidth` | number | `1280` | ความกว้าง viewport กำหนดเอง 320-3840 |
| `viewportHeight` | number | `720` | ความสูง viewport กำหนดเอง 320-2160 |

**ตัวอย่าง:**

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
```

**การตอบกลับ:**

```json
{
  "jobId": "uuid",
  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
  "originalSize": 0,
  "processedSize": 54321
}
```

### เส้นทางย่อยของเครื่องมือ {#tool-sub-routes}

เครื่องมือบางตัวมีเอนด์พอยต์เพิ่มเติมนอกเหนือจาก `POST /api/v1/tools/<section>/<toolId>` มาตรฐาน:

| Method | Path | คำอธิบาย |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | คืนค่า tool ID ยอดนิยม โดยย้อนกลับไปใช้รายการเริ่มต้นที่คัดสรรไว้เมื่อข้อมูลการใช้งานมีน้อย |
| `POST` | `/api/v1/tools/image/remove-background/effects` | ใช้เอฟเฟกต์พื้นหลัง (color/gradient/blur/shadow) โดยไม่ต้องรัน AI ใหม่ ใช้ mask ที่แคชไว้จากการลบครั้งแรก |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | อ่านเมทาดาทา EXIF/IPTC/XMP ที่มีอยู่จากรูปภาพ |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | ตรวจสอบฟิลด์เมทาดาทาก่อนลบ |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | เฟส 1: การตรวจจับใบหน้าด้วย AI + การลบพื้นหลัง คืนค่า face landmarks และข้อมูลที่แคชไว้ |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | เฟส 2: ครอป ปรับขนาด และปูภาพโดยใช้การวิเคราะห์ที่แคชไว้ ไม่มีการรัน AI ใหม่ |
| `POST` | `/api/v1/tools/image/gif-tools/info` | รับเมทาดาทา GIF (จำนวนเฟรม มิติ ระยะเวลา) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | รับเมทาดาทา PDF (จำนวนหน้า มิติ) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | สร้างตัวอย่างของหน้า PDF ที่ระบุ |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | รับเมทาดาทา PDF สำหรับพรีเซ็ต JPG เฉพาะ |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต JPG |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | รับเมทาดาทา PDF สำหรับพรีเซ็ต PNG เฉพาะ |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต PNG |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | รับเมทาดาทา PDF สำหรับพรีเซ็ต TIFF เฉพาะ |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต TIFF |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | แปลง SVG หลายไฟล์เป็นแรสเตอร์แบบแบตช์ |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | วิเคราะห์คุณภาพภาพและคืนค่าคำแนะนำการเพิ่มคุณภาพ |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | ตัวอย่างแบบเบาสำหรับการปรับพารามิเตอร์แบบสด คืนค่ารูปภาพที่ปรับให้เหมาะสมพร้อมส่วนหัวขนาด |

## การประมวลผลแบบแบตช์ {#batch-processing}

ใช้เครื่องมือที่รองรับแบตช์ทั่วไปกับหลายไฟล์พร้อมกัน คืนค่าไฟล์บีบอัด ZIP เส้นทางที่มีหลายไฟล์หรือหลายขั้นตอนกำหนดเอง เช่น การลงนาม PDF และเส้นทางพรีเซ็ต PDF-เป็น-รูปภาพ ใช้สัญญาเอนด์พอยต์ของตนเองแทนเส้นทาง `/batch` ทั่วไป

เครื่องมือ `ocr-pdf` รองรับเส้นทาง `/batch` ทั่วไปนี้

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F "files=@c.jpg" \
  -F 'settings={"quality":80}'
```

การทำงานพร้อมกันควบคุมโดย `CONCURRENT_JOBS` (ค่าเริ่มต้น: ตรวจจับอัตโนมัติจากคอร์ CPU) `MAX_BATCH_SIZE` จำกัดจำนวนไฟล์ต่อแบตช์ (ค่าเริ่มต้น: 100; ตั้งเป็น 0 สำหรับไม่จำกัด)

## ไปป์ไลน์ {#pipelines}

### รันไปป์ไลน์ {#execute-a-pipeline}

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'pipeline={"steps":[
    {"toolId":"resize","settings":{"width":1200}},
    {"toolId":"compress","settings":{"quality":80}},
    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
  ]}'

# Batch (multiple files → ZIP)
curl -X POST http://localhost:1349/api/v1/pipeline/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
```

เอาต์พุตของแต่ละขั้นตอนคืออินพุตของขั้นตอนถัดไป ไปป์ไลน์อนุญาต 20 ขั้นตอนโดยค่าเริ่มต้น กำหนดค่าได้ผ่าน `MAX_PIPELINE_STEPS` ตั้งค่า `MAX_PIPELINE_STEPS=0` เพื่อลบขีดจำกัด

### บันทึกและจัดการไปป์ไลน์ {#save-and-manage-pipelines}

| Method | Path | คำอธิบาย |
|--------|------|-------------|
| `POST` | `/api/v1/pipeline/save` | บันทึกไปป์ไลน์ที่ตั้งชื่อ (`name`, `description`, `steps[]`) |
| `GET` | `/api/v1/pipeline/list` | แสดงรายการไปป์ไลน์ที่บันทึกไว้ (ผู้ดูแลระบบเห็นทั้งหมด; ผู้ใช้เห็นของตนเอง) |
| `DELETE` | `/api/v1/pipeline/:id` | ลบ (เจ้าของหรือผู้ดูแลระบบ) |
| `GET` | `/api/v1/pipeline/tools` | แสดงรายการ tool ID ที่ใช้ได้กับขั้นตอนไปป์ไลน์ |

## การติดตามความคืบหน้า {#progress-tracking}

งานที่ทำงานนาน เครื่องมือที่เข้าคิว งานแบตช์ และไปป์ไลน์จะส่งความคืบหน้าแบบเรียลไทม์ผ่าน Server-Sent Events สตรีมความคืบหน้าเป็นสาธารณะและระบุด้วย job ID ดังนั้นไคลเอนต์ไม่จำเป็นต้องส่งส่วนหัว Authorization เพื่ออ่าน

```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
```

รูปแบบอีเวนต์:
```
data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
```

คุณสามารถขอยกเลิกงานที่เข้าคิวหรือกำลังทำงานได้ด้วย `POST /api/v1/jobs/:jobId/cancel` การตอบกลับคือ `{"canceled":true|false}`

## คลังไฟล์ {#file-library}

การจัดเก็บไฟล์แบบถาวรพร้อมประวัติเวอร์ชัน

| Method | Path | คำอธิบาย |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | อัปโหลดไฟล์ไปยัง workspace (การประมวลผลชั่วคราว) |
| `POST` | `/api/v1/files/upload` | อัปโหลดไฟล์ไปยังคลังไฟล์ถาวร |
| `POST` | `/api/v1/files/save-result` | บันทึกผลการประมวลผลของเครื่องมือเป็นเวอร์ชันไฟล์ใหม่ |
| `GET` | `/api/v1/files` | แสดงรายการไฟล์ที่บันทึกไว้ (แบ่งหน้า พร้อมการค้นหา) |
| `GET` | `/api/v1/files/:id` | รับเมทาดาทาไฟล์ + สายเวอร์ชัน |
| `GET` | `/api/v1/files/:id/download` | ดาวน์โหลดไฟล์ |
| `GET` | `/api/v1/files/:id/thumbnail` | รับภาพขนาดย่อ JPEG 300px |
| `DELETE` | `/api/v1/files` | ลบไฟล์และสายเวอร์ชันของไฟล์แบบกลุ่ม (body: `{ ids: [...] }`) |
| `POST` | `/api/v1/fetch-urls` | ดึง URL ระยะไกลเข้าสู่ workspace สำหรับการนำเข้าแบบอิง URL |
| `POST` | `/api/v1/preview` | สร้างตัวอย่าง WebP ที่เข้ากันได้กับเบราว์เซอร์ (สำหรับรูปแบบ HEIC/HEIF/RAW) |
| `GET` | `/api/v1/files/:id/preview` | สตรีมตัวอย่างที่แคชไว้หรือสร้างขึ้นที่เข้ากันได้กับเบราว์เซอร์สำหรับ PDF, เอกสาร office, วิดีโอ หรือไฟล์เสียงที่บันทึกไว้ |
| `POST` | `/api/v1/preview/generate` | สร้างตัวอย่าง MP4 หรือ MP3 แบบทันทีสำหรับไฟล์สื่อที่อัปโหลดโดยไม่ต้องบันทึกก่อน |
| `GET` | `/api/v1/download/:jobId/:filename` | ดาวน์โหลดไฟล์ที่ประมวลผลแล้วจาก workspace |

หากต้องการบันทึกผลลัพธ์ของเครื่องมือไปยังคลังโดยอัตโนมัติ ให้รวม `fileId` เป็นฟิลด์ multipart form ที่อ้างอิงถึงไฟล์ในคลังที่มีอยู่ ผลลัพธ์ที่ประมวลผลแล้วจะถูกบันทึกเป็นเวอร์ชันใหม่

## การจัดการ API Key {#api-key-management}

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | ยืนยันตัวตน | สร้างคีย์ใหม่ - แสดงเพียงครั้งเดียว |
| `GET` | `/api/v1/api-keys` | ยืนยันตัวตน | แสดงรายการคีย์ (name, id, lastUsedAt - ไม่ใช่คีย์ดิบ) |
| `DELETE` | `/api/v1/api-keys/:id` | ยืนยันตัวตน | ลบคีย์ |

## ทีม {#teams}

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/teams` | ผู้ดูแลระบบ (`teams:manage`) | แสดงรายการทีม |
| `POST` | `/api/v1/teams` | ผู้ดูแลระบบ (`teams:manage`) | สร้างทีม |
| `PUT` | `/api/v1/teams/:id` | ผู้ดูแลระบบ (`teams:manage`) | เปลี่ยนชื่อทีม |
| `DELETE` | `/api/v1/teams/:id` | ผู้ดูแลระบบ (`teams:manage`) | ลบทีม (ไม่สามารถลบทีมเริ่มต้นหรือทีมที่มีสมาชิก) |

## การตั้งค่า {#settings}

การกำหนดค่าขณะรันใช้ชุดคีย์ที่ระบบรู้จักแบบปิด การอ่านต้องมี `settings:read` และการเขียนต้องมี `settings:write` ส่วนคีย์ด้านความปลอดภัยและการปฏิบัติตามข้อกำหนดยังต้องมี `security:manage` หรือ `compliance:manage` เพิ่มเติม การตั้งค่าที่เป็นความลับต้องมีสิทธิ์ผู้ดูแลระบบเต็มรูปแบบ ส่วนข้อมูลประจำตัวและสถานะที่จัดการโดย endpoint เฉพาะจะเป็นแบบอ่านอย่างเดียวที่นี่ ระบบจะตรวจสอบการอัปเดตแบบกลุ่มทั้งหมดก่อนเขียนค่าใด ๆ

| Method | Path | คำอธิบาย |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | รับการตั้งค่าทั้งหมด |
| `PUT` | `/api/v1/settings` | อัปเดตการตั้งค่าแบบกลุ่ม (JSON body พร้อมคู่คีย์-ค่า) |
| `GET` | `/api/v1/settings/:key` | รับการตั้งค่าที่ระบุตามคีย์ |

ตัวอย่างคีย์: `disabledTools` (อาร์เรย์ JSON ของ ID เครื่องมือ), `enableExperimentalTools` (ค่าบูลีน), `loginAttemptLimit` (นโยบายความปลอดภัย) และ `auditRetentionDays` (นโยบายการปฏิบัติตามข้อกำหนด) ระบบจะปฏิเสธคีย์ที่ไม่รู้จัก

## ค่าปรับตั้ง {#preferences}

ค่าปรับตั้งต่อผู้ใช้แยกจากการตั้งค่าของอินสแตนซ์ ผู้ใช้ที่ยืนยันตัวตนแล้วทุกคนสามารถอ่านและอัปเดตแผนที่ค่าปรับตั้งของตนเองได้

| Method | Path | คำอธิบาย |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | รับค่าปรับตั้งของผู้ใช้ปัจจุบันในรูปแบบ `{ "preferences": { ... } }` |
| `PUT` | `/api/v1/preferences` | เพิ่มหรืออัปเดตคีย์ค่าปรับตั้งหนึ่งรายการขึ้นไปสำหรับผู้ใช้ปัจจุบัน |

## บทบาท {#roles}

การจัดการบทบาทกำหนดเองพร้อมสิทธิ์แบบละเอียด

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | ผู้ดูแลระบบ (`audit:read`) | แสดงรายการบทบาททั้งหมดพร้อมจำนวนผู้ใช้ |
| `POST` | `/api/v1/roles` | ผู้ดูแลระบบ (`security:manage`) | สร้างบทบาทกำหนดเอง (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | ผู้ดูแลระบบ (`security:manage`) | อัปเดตบทบาทกำหนดเอง (ไม่สามารถแก้ไขบทบาทในตัว) |
| `DELETE` | `/api/v1/roles/:id` | ผู้ดูแลระบบ (`security:manage`) | ลบบทบาทกำหนดเอง (ไม่สามารถลบบทบาทในตัว; ผู้ใช้ที่ได้รับผลกระทบจะกลับไปใช้บทบาท `user`) |

สิทธิ์ที่มีให้ (17): `tools:use`, `files:own`, `files:all`, `apikeys:own`, `apikeys:all`, `pipelines:own`, `pipelines:all`, `settings:read`, `settings:write`, `users:manage`, `teams:manage`, `features:manage`, `system:health`, `audit:read`, `compliance:manage`, `webhooks:manage`, `security:manage`

## บันทึกการตรวจสอบ {#audit-log}

เอนด์พอยต์เฉพาะผู้ดูแลระบบสำหรับตรวจสอบการกระทำที่เกี่ยวข้องกับความปลอดภัย

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/audit-log` | ผู้ดูแลระบบ (`audit:read`) | บันทึกการตรวจสอบแบบแบ่งหน้าพร้อมตัวกรองที่ไม่บังคับ |

พารามิเตอร์คิวรี:

| พารามิเตอร์ | คำอธิบาย |
|-----------|-------------|
| `page` | หมายเลขหน้า (ค่าเริ่มต้น: 1) |
| `limit` | รายการต่อหน้า (ค่าเริ่มต้น: 50, สูงสุด: 100) |
| `action` | กรองตามประเภทการกระทำ (เช่น `ROLE_CREATED`, `ROLE_DELETED`) |
| `ip` | กรองตามที่อยู่ IP ต้นทาง |
| `from` | กรองรายการหลังวันที่ ISO 8601 นี้ |
| `to` | กรองรายการก่อนวันที่ ISO 8601 นี้ |

## การวิเคราะห์ {#analytics}

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | สาธารณะ | รับการกำหนดค่าการวิเคราะห์ที่มีผล (PostHog key, Sentry DSN, sample rate) คีย์ DSN และ instance ID จะว่างเปล่าเมื่อปิดการวิเคราะห์ ไม่ว่าจะจากการ bake ตอนคอมไพล์หรือการตั้งค่า `analyticsEnabled` ของอินสแตนซ์ |
| `POST` | `/api/v1/feedback` | ยืนยันตัวตน | ส่งความคิดเห็นของผู้ใช้อย่างชัดแจ้งไปยังโปรเจกต์ PostHog ที่กำหนดค่าไว้เป็น `feedback_submitted` เส้นทางนี้เคารพเกตการวิเคราะห์ จำกัดอัตราการส่ง ตัดฟิลด์ติดต่อออกเว้นแต่ `contactOk` เป็นจริง และไม่รับเนื้อหาไฟล์ ชื่อไฟล์ เส้นทางอัปโหลด หรือข้อความข้อผิดพลาดส่วนตัวแบบดิบ เมื่อปิดการวิเคราะห์ จะคืนค่า `{ "ok": true, "accepted": false }` |
| `PUT` | `/api/v1/settings` | ผู้ดูแลระบบ (`settings:write`) | ตั้งค่าการเลือกไม่เข้าร่วมทั่วทั้งอินสแตนซ์ ส่ง JSON body `{ "analyticsEnabled": "false" }` เพื่อปิดการวิเคราะห์สำหรับทุกคน หรือ `"true"` เพื่อเปิดกลับมาอีกครั้ง |

## ฟีเจอร์ / AI Bundles {#features-ai-bundles}

จัดการ AI feature bundles (ติดตั้ง/ถอนการติดตั้งแพ็กเกจโมเดล AI ในสภาพแวดล้อม Docker) ควรใช้เอนด์พอยต์การติดตั้งระดับเครื่องมือเมื่อเปิดใช้งานเครื่องมือจากระบบอัตโนมัติกำหนดเอง: เครื่องมือ AI บางตัวต้องการ shared bundle มากกว่าหนึ่งรายการ และเอนด์พอยต์นี้จะข้าม bundle ที่ติดตั้งแล้วโดยเข้าคิวเฉพาะที่ขาดหายไป

OCR เป็นการปรับปรุงทางเลือกมากกว่าการพึ่งพาอย่างหนัก ระดับ `fast` Tesseract ทำงานได้โดยไม่ต้องแพ็ค `POST /api/v1/admin/features/ocr/install` ติดตั้งชุด RapidOCR ที่ลงนามแล้วสำหรับ `balanced` และ `best` บน Linux amd64 หรือ arm64 รันไทม์ OCR ที่แม่นยำใช้ CPU บนโฮสต์ CPU เท่านั้นและ NVIDIA และต้องการหน่วยความจำที่มีประสิทธิภาพอย่างน้อย 4 GiB (ขีดจำกัดคอนเทนเนอร์ cgroup ที่กำหนดค่าไว้ มิฉะนั้น หน่วยความจำโฮสต์) SnapOtter รายงาน `requiredMemoryBytes`, `effectiveMemoryBytes` และเหตุผลด้านความเข้ากันได้ของ `insufficient-memory` และปฏิเสธการติดตั้งที่เข้ากันไม่ได้ก่อนที่จะดาวน์โหลด ข้อกำหนดหน่วยความจำนี้ใช้ไม่ได้กับ `fast` ชุดนี้มีขนาดประมาณ 208-234 MiB สำหรับดาวน์โหลดและติดตั้ง 409-488 MiB ขึ้นอยู่กับเป้าหมาย ดัชนีที่ลงนามจะผูกขนาดที่แน่นอนที่บังคับใช้ระหว่างการติดตั้ง

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/features` | ยืนยันตัวตน | แสดงรายการ feature bundle ทั้งหมดและสถานะการติดตั้ง |
| `POST` | `/api/v1/admin/features/:bundleId/install` | ผู้ดูแลระบบ (`features:manage`) | ติดตั้ง feature bundle (แบบอะซิงโครนัส คืนค่า `jobId` สำหรับการติดตามความคืบหน้า) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | ผู้ดูแลระบบ (`features:manage`) | ติดตั้งทุก bundle ที่เครื่องมือต้องการ; คืนค่าสถานะเข้าคิว/ข้ามต่อ bundle |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | ผู้ดูแลระบบ (`features:manage`) | ถอนการติดตั้ง feature bundle และล้างไฟล์โมเดล |
| `GET` | `/api/v1/admin/features/disk-usage` | ผู้ดูแลระบบ (`features:manage`) | รับการใช้พื้นที่ดิสก์รวมของโมเดล AI |
| `POST` | `/api/v1/admin/features/import` | ผู้ดูแลระบบ (`features:manage`) | นำเข้าชุด AI เดิม (`file`) หรือรุ่น OCR ออฟไลน์ที่ลงนามแล้ว (`index` บวก `archive`) |

การนำเข้า OCR แบบมีช่องว่างอากาศจะต้องรวม `ocr-runtime-index.json` ที่ลงนามแล้วของรุ่นและไฟล์เก็บถาวรของแพลตฟอร์มที่ตรงกัน SnapOtter ใช้ลายเซ็น Ed25519 แฮชอาร์ติแฟกต์ ความเข้ากันได้ การแยก และการทดสอบควันที่ใช้โดยการติดตั้งออนไลน์:

```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
  -H "Authorization: Bearer <admin-token>" \
  -F "index=@ocr-runtime-index.json" \
  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```

ใช้ไฟล์เก็บถาวร `linux-arm64-cpu-py311` บน arm64 อาร์ติแฟกต์ที่ลงนามสำหรับเป้าหมายอื่นถูกปฏิเสธแทนที่จะติดตั้ง

## การดำเนินงานของผู้ดูแลระบบ {#admin-operations}

เอนด์พอยต์ปฏิบัติการสำหรับการสังเกตการณ์ การสนับสนุน การรายงานการใช้งาน และสถานะการสำรองข้อมูล

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/admin/log-level` | ผู้ดูแลระบบ (`settings:write`) | อ่านระดับ log รันไทม์ปัจจุบัน |
| `POST` | `/api/v1/admin/log-level` | ผู้ดูแลระบบ (`settings:write`) | เปลี่ยนระดับ log รันไทม์ (`fatal`, `error`, `warn`, `info`, `debug`, `trace` หรือ `silent`) |
| `GET` | `/api/v1/metrics` | ผู้ดูแลระบบ (`system:health`) | Prometheus metrics ในรูปแบบข้อความ |
| `GET` | `/api/v1/admin/support-bundle` | ผู้ดูแลระบบ (`system:health`) | ดาวน์โหลด ZIP ชุดสนับสนุนการวินิจฉัยที่ปกปิดข้อมูลแล้ว |
| `GET` | `/api/v1/admin/usage` | ผู้ดูแลระบบ (`audit:read`) | ข้อมูลแดชบอร์ดการใช้งาน พร้อมพารามิเตอร์คิวรี `days` ที่ไม่บังคับ |
| `GET` | `/api/v1/admin/backup-status` | ผู้ดูแลระบบ (`system:health`) | อ่านเมทาดาทาการสำรองข้อมูลล่าสุดและสถานะความใหม่ |
| `POST` | `/api/v1/admin/backup-status` | ผู้ดูแลระบบ (`system:health`) | บันทึกการสำรองข้อมูลที่เสร็จสมบูรณ์ (`type`, `sizeBytes` ที่ไม่บังคับ, `notes` ที่ไม่บังคับ) |

## Enterprise API {#enterprise-apis}

เส้นทางเหล่านี้ถูกเกตด้วยไลเซนส์ตามฟีเจอร์ enterprise ที่เกี่ยวข้อง ยังคงต้องมีสิทธิ์ SnapOtter ที่ระบุไว้

**ผู้ดูแลระบบในตัวที่มีสิทธิ์เต็มรูปแบบ** หมายถึงผู้ดำเนินการที่ผ่านการยืนยันตัวตนซึ่งมีบทบาท `admin` และมีชุดสิทธิ์ผู้ดูแลระบบที่มีผลครบทั้งหมด ขอบเขตคีย์ API ที่ขาดสิทธิ์ผู้ดูแลระบบแม้แต่รายการเดียวจะไม่เข้าเงื่อนไข

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/enterprise/audit/export` | ผู้ดูแลระบบ (`audit:read`) | ส่งออกรายการการตรวจสอบเป็น JSON หรือ CSV พร้อมตัวกรอง |
| `GET` | `/api/v1/enterprise/config/export` | ผู้ดูแลระบบในตัวที่มีสิทธิ์เต็มรูปแบบ | ส่งออกการกำหนดค่าอินสแตนซ์ บทบาทกำหนดเอง และทีมที่ปกปิดข้อมูลแล้ว |
| `POST` | `/api/v1/enterprise/config/import` | ผู้ดูแลระบบในตัวที่มีสิทธิ์เต็มรูปแบบ | นำเข้าการกำหนดค่า พร้อมการทดลองรันที่ไม่บังคับ |
| `GET` | `/api/v1/enterprise/ip-allowlist` | ผู้ดูแลระบบ (`security:manage`) | อ่านรายการอนุญาต CIDR ที่กำหนดค่าไว้ |
| `PUT` | `/api/v1/enterprise/ip-allowlist` | ผู้ดูแลระบบ (`security:manage`) | อัปเดตรายการอนุญาต CIDR พร้อมการป้องกันการล็อกตัวเองออก |
| `GET` | `/api/v1/enterprise/legal-hold` | ผู้ดูแลระบบ (`compliance:manage`) | แสดงรายการการระงับทางกฎหมายของผู้ใช้และทีม |
| `PUT` | `/api/v1/enterprise/legal-hold` | ผู้ดูแลระบบ (`compliance:manage`) | ใช้หรือปลดการระงับทางกฎหมายกับผู้ใช้หรือทีม |
| `POST` | `/api/v1/enterprise/scim/token` | ผู้ดูแลระบบ (`users:manage`) | สร้าง SCIM bearer token คืนค่าเพียงครั้งเดียว |
| `DELETE` | `/api/v1/enterprise/scim/token` | ผู้ดูแลระบบ (`users:manage`) | เพิกถอน SCIM bearer token ปัจจุบัน |
| `GET` | `/api/v1/enterprise/siem/config` | ผู้ดูแลระบบ (`webhooks:manage`) | อ่านการกำหนดค่าการส่งต่อ SIEM |
| `PUT` | `/api/v1/enterprise/siem/config` | ผู้ดูแลระบบ (`webhooks:manage`) | อัปเดตการกำหนดค่าการส่งต่อ SIEM |
| `GET` | `/api/v1/enterprise/webhooks` | ผู้ดูแลระบบ (`webhooks:manage`) | แสดงรายการปลายทาง webhook |
| `POST` | `/api/v1/enterprise/webhooks` | ผู้ดูแลระบบ (`webhooks:manage`) | สร้างปลายทาง webhook |
| `PUT` | `/api/v1/enterprise/webhooks/:index` | ผู้ดูแลระบบ (`webhooks:manage`) | อัปเดตปลายทาง webhook |
| `DELETE` | `/api/v1/enterprise/webhooks/:index` | ผู้ดูแลระบบ (`webhooks:manage`) | ลบปลายทาง webhook |
| `POST` | `/api/v1/enterprise/webhooks/:index/test` | ผู้ดูแลระบบ (`webhooks:manage`) | ส่ง payload webhook ทดสอบ |
| `POST` | `/api/v1/enterprise/users/:id/export` | ผู้ดูแลระบบ (`compliance:manage`) | เริ่มงานส่งออกข้อมูลผู้ใช้ตาม GDPR |
| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | ผู้ดูแลระบบ (`compliance:manage`) | อ่านสถานะการส่งออก GDPR และ URL ดาวน์โหลด |
| `DELETE` | `/api/v1/enterprise/users/:id/purge` | ผู้ดูแลระบบ (`compliance:manage`) | ล้างข้อมูลของผู้ใช้อย่างถาวรหลังการยืนยัน |
| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | ผู้ดูแลระบบ (`compliance:manage`) | ล้างข้อมูลของทีมอย่างถาวรหลังการยืนยัน |
| `GET` | `/api/v1/admin/version` | ผู้ดูแลระบบ (`system:health`) | อ่านเมทาดาทาเวอร์ชันของแอป build, Node และ schema |
| `GET` | `/api/v1/admin/migrations/pending` | ผู้ดูแลระบบ (`system:health`) | เปรียบเทียบ migration ที่แพ็กเกจไว้กับ migration ที่ใช้แล้ว |
| `GET` | `/api/v1/admin/upgrade-check` | ผู้ดูแลระบบ (`system:health`) | รันการตรวจสอบความพร้อมในการอัปเกรด |

### SCIM 2.0 {#scim-2-0}

เอนด์พอยต์การค้นพบ SCIM เป็นสาธารณะ เอนด์พอยต์ผู้ใช้และกลุ่มต้องใช้ SCIM bearer token ที่สร้างไว้ด้านบน

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | สาธารณะ | ความสามารถของเซิร์ฟเวอร์ SCIM |
| `GET` | `/api/v1/scim/v2/Schemas` | สาธารณะ | การค้นพบ schema ของ SCIM |
| `GET` | `/api/v1/scim/v2/ResourceTypes` | สาธารณะ | การค้นพบประเภททรัพยากรของ SCIM |
| `GET` | `/api/v1/scim/v2/Users` | SCIM token | แสดงรายการผู้ใช้ พร้อมตัวกรอง SCIM ที่ไม่บังคับ |
| `POST` | `/api/v1/scim/v2/Users` | SCIM token | สร้างผู้ใช้ |
| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM token | รับผู้ใช้ |
| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM token | แทนที่ผู้ใช้ |
| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM token | ปิดใช้งานผู้ใช้แบบ soft |
| `GET` | `/api/v1/scim/v2/Groups` | SCIM token | แสดงรายการทีมเป็นกลุ่ม SCIM |
| `POST` | `/api/v1/scim/v2/Groups` | SCIM token | สร้างทีม |
| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM token | รับทีม |
| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM token | แทนที่ทีมและสมาชิกกลุ่ม |
| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM token | ลบทีม |

## เทมเพลตมีม {#meme-templates}

API สนับสนุนสำหรับเครื่องมือสร้างมีม

| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
|--------|------|--------|-------------|
| `GET` | `/api/v1/meme-templates` | ยืนยันตัวตน | แสดงรายการเทมเพลตมีมที่มีทั้งหมดพร้อมตำแหน่งกล่องข้อความ |
| `GET` | `/api/v1/meme-templates/full/:filename` | ยืนยันตัวตน | ให้บริการรูปภาพเทมเพลตขนาดเต็ม |
| `GET` | `/api/v1/meme-templates/thumbs/:filename` | ยืนยันตัวตน | ให้บริการภาพขนาดย่อของเทมเพลต |
| `GET` | `/api/v1/meme-templates/fonts/:filename` | ยืนยันตัวตน | ให้บริการไฟล์ฟอนต์ที่ใช้สำหรับการเรนเดอร์ข้อความมีม |

## การตอบกลับข้อผิดพลาด {#error-responses}

ข้อผิดพลาดทั้งหมดคืนค่าเป็น JSON:

```json
{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}
```

| สถานะ | ความหมาย |
|--------|---------|
| 400 | คำขอไม่ถูกต้อง / การตรวจสอบล้มเหลว |
| 401 | ยังไม่ได้ยืนยันตัวตน |
| 403 | สิทธิ์ไม่เพียงพอ |
| 404 | ไม่พบทรัพยากร |
| 413 | ไฟล์ใหญ่เกินไป (ดู `MAX_UPLOAD_SIZE_MB`) |
| 422 | การประมวลผลล้มเหลวหลังการตรวจสอบ |
| 429 | ถูกจำกัดอัตรา (ดู `RATE_LIMIT_PER_MIN`) |
| 501 | ไม่ได้ติดตั้ง AI feature bundle ที่จำเป็น (`FEATURE_NOT_INSTALLED`) |
| 500 | ข้อผิดพลาดภายในเซิร์ฟเวอร์ |