راهنمای API خط وب ابزار

احراز هویت

کلید خود را از بخش کلیدهای API بسازید و در هدر هر درخواست قرار دهید. دسترسی API نیازمند پلن دارای API است.

Authorization: Bearer kt_xxxxxxxxxxxxxxxxxxxxxxxx

پردازش تصویر

POST /api/v1/image

بدنه به‌صورت multipart/form-data. فیلد file و format (یکی از webp، avif، png، jpeg، gif) الزامی‌اند. فیلدهای اختیاری: quality (۱۰ تا ۱۰۰)، width، height، keepAspectRatio، rotate، flipH، flipV، grayscale، sharpen، blur، stripMetadata. پاسخ، بایت‌های تصویر پردازش‌شده است.

curl -X POST https://YOUR_DOMAIN/api/v1/image \
  -H "Authorization: Bearer kt_xxx" \
  -F "file=@photo.png" \
  -F "format=webp" \
  -F "quality=82" \
  -F "width=1200" \
  --output out.webp

واکاوی سایت

POST /api/v1/analyze

بدنه به‌صورت JSON با url (عمومی) و strategy اختیاری (mobile یا desktop). پاسخ، گزارش کامل Lighthouse است. اجرای هر تحلیل ممکن است تا حدود ۹۰ ثانیه طول بکشد.

curl -X POST https://YOUR_DOMAIN/api/v1/analyze \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","strategy":"mobile"}'

واکاوی غیرهمزمان (صف)

POST /api/v1/analyze/async → GET /api/v1/jobs/{id}

برای پرهیز از تایم‌اوت در تحلیل‌های طولانی، کار را در صف ثبت کنید. پاسخ فوری شامل jobId است؛ سپس وضعیت را poll کنید تا status برابر done شود و result برگردد.

# 1) enqueue -> 202 { jobId, status, poll }
curl -X POST https://YOUR_DOMAIN/api/v1/analyze/async \
  -H "Authorization: Bearer kt_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# 2) poll -> { status: queued|running|done|failed, result }
curl https://YOUR_DOMAIN/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer kt_xxx"

کدهای خطا