مستندات وبسرویس برنامهنویسان و راهنمای اتصال API
اتصال خودکار اسکریپتها، سیستمهای بکاند و سایتهای وردپرسی به موتور فشردهسازی بیسکو وب
هنوز کلید اختصاصی API ندارید؟
با عضویت آنی و رایگان، کلید اختصاصی خود را همراه با 10 سهمیه تبدیل رایگان ماهانه در چند ثانیه تحویل بگیرید.
/compress
هدرهای اجباری درخواست (Request Headers):
| عنوان هدر | مقدار | توضیح |
|---|---|---|
| Authorization | Bearer <YOUR_API_KEY> | کلید احراز هویت شما که از پنل کاربری دریافت کردهاید |
| Accept | application/json | مشخصکننده نوع داده بازگشتی |
پارامترهای ارسالی (Body Parameters - Multipart Form):
| نام فیلد | نوع | الزام | مقدار پیشفرض | توضیحات |
|---|---|---|---|---|
| image | File | اجباری | - | فایل تصویر خام (JPG, PNG, WebP, GIF, AVIF تا سقف ۱۰ مگابایت) |
| format | String | اختیاری | webp | فرمت خروجی مورد نظر: webp، original، jpg، png |
| quality | Integer | اختیاری | 82 | کیفیت فشردهسازی عددی بین ۲۰ تا ۱۰۰ (پیشنهادی: ۸۰ الی ۸۵) |
| max_width | Integer | اختیاری | null | حداکثر عرض تصویر (در صورت بزرگتر بودن، تغییر اندازه متناسب انجام میشود) |
| max_height | Integer | اختیاری | null | حداکثر ارتفاع تصویر (در صورت بزرگتر بودن، تغییر اندازه متناسب انجام میشود) |
نمونه کدهای آماده فراخوانی (SDK & Code Snippets):
کلید API شما بهصورت خودکار در کدها جایگذاری شده استcurl -X POST https://biscoweb.com/api/v1/optimizer/compress \
-H "Authorization: Bearer " \
-H "Accept: application/json" \
-F "image=@/path/to/your/image.png" \
-F "format=webp" \
-F "quality=82"
<?php
$apiKey = '';
$imagePath = '/path/to/your/image.png';
$ch = curl_init('https://biscoweb.com/api/v1/optimizer/compress');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Accept: application/json',
],
CURLOPT_POSTFIELDS => [
'image' => new CURLFile($imagePath),
'format' => 'webp',
'quality' => 82,
],
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result['success'] ?? false) {
echo "بهینهسازی موفق! لینک دانلود: " . $result['data']['url'];
echo "میزان صرفهجویی: " . $result['data']['savings_percent'] . "%";
} else {
echo "خطا: " . ($result['message'] ?? 'نامشخص');
}
import requests
API_KEY = ''
URL = 'https://biscoweb.com/api/v1/optimizer/compress'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
files = {
'image': open('/path/to/your/image.png', 'rb')
}
data = {
'format': 'webp',
'quality': 82
}
response = requests.post(URL, headers=headers, files=files, data=data)
result = response.json()
if result.get('success'):
print(f"Compressed URL: {result['data']['url']}")
print(f"Savings: {result['data']['savings_percent']}%")
else:
print(f"Error: {result.get('message')}")
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('image', fs.createReadStream('/path/to/your/image.png'));
form.append('format', 'webp');
form.append('quality', '82');
axios.post('https://biscoweb.com/api/v1/optimizer/compress', form, {
headers: {
...form.getHeaders(),
'Authorization': 'Bearer ',
'Accept': 'application/json'
}
})
.then(res => {
console.log('فایل بهینهشده:', res.data.data.url);
console.log('صرفهجویی:', res.data.data.savings_percent + '%');
})
.catch(err => {
console.error('خطا:', err.response?.data?.message || err.message);
});
<?php
// اتصال از طریق توابع استاندارد وردپرس
$api_key = '';
$file_path = get_attached_file($attachment_id);
$response = wp_remote_post('https://biscoweb.com/api/v1/optimizer/compress', [
'timeout' => 45,
'headers' => [
'Authorization' => 'Bearer ' . $api_key,
'Accept' => 'application/json',
],
'body' => [
'image' => curl_file_create($file_path),
'format' => 'webp',
'quality' => 82,
],
]);
if (!is_wp_error($response)) {
$body = json_decode(wp_remote_retrieve_body($response), true);
if ($body['success'] ?? false) {
$optimized_url = $body['data']['url'];
// ذخیره یا جایگزینی تصویر در وردپرس
}
}
نمونه پاسخ موفق (HTTP 200 OK):
{
"success": true,
"data": {
"url": "https://biscoweb.com/storage/optimizer/output/biscoweb_65a3d0f_banner.webp",
"relative_path": "optimizer/output/biscoweb_65a3d0f_banner.webp",
"output_filename": "biscoweb_65a3d0f_banner.webp",
"original_size": 1845200,
"compressed_size": 312450,
"savings_percent": 83.1,
"original_size_formatted": "1.76 MB",
"compressed_size_formatted": "305.1 KB",
"bytes_saved_formatted": "1.46 MB",
"format_from": "png",
"format_to": "webp",
"width": 1920,
"height": 1080,
"duration_ms": 138
},
"remaining_quota": 485
}
کدهای خطای متداول (HTTP Status Codes):
| کد وضعیت | وضعیت | علت و راهحل |
|---|---|---|
| 401 | Unauthorized | کلید API در هدر Authorization ارسال نشده یا اشتباه است. |
| 403 | Quota Exceeded | سقف رایگان ماهانه و اعتبار شارژی شما به اتمام رسیده است. از پنل کاربری بسته تهیه فرمایید. |
| 422 | Validation Error | فایل ارسال نشده، فرمت غیرمجاز است یا حجم تصویر بیشتر از سقف مجاز (۱۰ مگابایت) است. |
| 429 | Rate Limited | تعداد فراخوانیهای شما از سقف ۱۲۰ درخواست در دقیقه عبور کرده است. |
/me
با فراخوانی این متد میتوانید بدون کسر اعتبار، وضعیت باقیمانده تبدیلهای مجاز حساب خود را در هر لحظه استعلام کنید.
{
"success": true,
"data": {
"key_name": "کلید پیشفرض توسعهدهنده",
"is_active": true,
"monthly_quota": 500,
"used_this_month": 15,
"remaining_monthly": 485,
"extra_credits": 2000,
"total_remaining": 2485,
"total_used": 142,
"total_bytes_saved_mb": 182.4
}
}