شعار صورة إلى URL

وثائق 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"
}