وثائق API
يتطلب الوصول إلى API اشتراكاً نشطاً في Pro أو Premium. صادق بمفتاح API ثم ارفع الصور إلى نفس المكتبة التي تراها في لوحة التحكم. الحصص مطابقة لخطتك المدفوعة على الموقع.
رفع صورة
أرسل POST إلى /api/v1/upload بـ multipart/form-data.
المعاملات
Authorization- مطلوب. ترويسة الطلب. الصيغة: Bearer مفتاح_API_الخاص_بك.
file- مطلوب. ملف ثنائي أو بيانات base64.
name- اختياري. اسم الملف؛ يُكتشف تلقائياً عند رفع ملف محلي عبر multipart.
مثال على الطلب
ملف ثنائي
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=@./product.jpg"
Base64
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \ -F "name=pixel.gif"
عند رفع ملف محلي استخدم دائماً POST. الرفع عبر GET غير مدعوم.
حقول الاستجابة
id- معرّف المورد في مكتبتك.
url- رابط CDN لاستخدامه في صفحات المنتجات.
fileName- اسم الملف الأصلي.
fileSize- حجم الملف بالبايت.
mimeType- نوع MIME للملف المرفوع.
createdAt- وقت الرفع بتوقيت UTC، بالصيغة YYYY-MM-DD HH:mm:ss.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileName": "product.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}عرض الصور
GET /api/v1/images مع page و pageSize اختياريين (الحد الأقصى 100).
curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
حقول الاستجابة
resources- مصفوفة الصور: id و fileName و url و fileSize و mimeType و createdAt.
page- رقم الصفحة الحالية.
pageSize- عدد العناصر في الصفحة.
total- إجمالي الصور في المكتبة.
{
"resources": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fileName": "product.jpg",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}
],
"page": 1,
"pageSize": 20,
"total": 1
}حذف صورة
DELETE /api/v1/images/:id. يحذف الملف من التخزين ومكتبتك.
curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
حقول الاستجابة
success- true عند حذف الصورة.
{ "success": true }الحدود
API غير متاح على الخطة المجانية. Pro و Premium يستخدمان حدود الرفع والتخزين وحجم الملف لخطتك. عند تجاوز حد ما، يعيد API خطأ يتضمن upgradeUrl.
الأخطاء
الطلبات الفاشلة تعيد رمز خطأ. أخطاء الحصة قد تتضمن upgradeUrl.
dailyLimitReached— تم بلوغ حد الرفع اليومي (HTTP 429).storageLimitReached— تم تجاوز حصة التخزين (HTTP 413).fileTooLarge— الملف أكبر مما تسمح به خطتك (HTTP 400).401— مفتاح API مفقود أو غير صالح أو ملغى.
{
"error": "dailyLimitReached",
"errorParams": { "limit": 1000 },
"plan": "paid",
"limit": 1000,
"upgradeUrl": "https://www.phototourl.com/pricing"
}