واجهة برمجة تطبيقات Vehicle Imagery v1.2.0

صور سيارات عالية الجودة من كل علامة تجارية، نموذج، سنة، تباين، ترميز، ووجهة — يتم تسليمها كروابط CDN موقعة مع تنسيق، حجم، نسبة العرض إلى الارتفاع، لون الطلاء، ظل، شفافية، توضيح، وتأثير مرآة الأرضية.

رابط أساسي

جميع نقاط النهاية تعمل تحت https://api.vehicleimagery.com

التحقق من الهوية

كل طلب يحتاج إلى مفتاح واجهة برمجة التطبيقات الخاص بك في عنوان x-api-key

curl -H "x-api-key: YOUR_API_KEY" https://api.vehicleimagery.com/api/brands

ما قد يفعله مفتاحك (تنسيقات، نسب، ميزات، علامات تجارية) يتم إرجاعه بواسطة /api/me. نقاط نهاية الوثائق (/api/openapi.json, /api/docs) عامة ولا تحتاج إلى مفتاح.

طريقتان للدخول

تعرف على السيارة؟ استعرض الكتالوج: brand → model → year → variant → trim → view. هل لديك سيارة حقيقية؟ استخدم إضافات البحث — GET /vin/{vin} أو GET /plate/{plate} تحويل رقم VIN أو رقم التسجيل مباشرة إلى بيانات السيارة بالإضافة إلى صور الاستوديو لتلك السيارة، مع تطبيق لون الطلاء الحقيقي حيثما كان متاحًا. يتم تمكين الإضافات لكل مفتاح؛ /api/me يظهر ما يمكن أن يفعله المفتاح الخاص بك.

كيف يعمل ذلك

1. استعرض الكتالوج حتى تصل إلى سيارة واحدة: العلامة التجارية → النموذج → السنة → التكوين → الطراز → العرض، على سبيل المثال GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
2. حل صورة عن طريق إضافة العرض + الخيارات: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → يعيد البيانات بالإضافة إلى رابط صورة موقعة image_url.
3. أدرج image_url مباشرة في <img> الخاص بك. إنه موقّع ومقفّل التحويل؛ يتم توليد البايتات عند الطلب الأول وتخزينها في CDN لمدة TTL خطةك (الافتراضي 7 أيام).

خيارات الصورة

أضف إلى أي طلب للصورة: format, resolution, ratio, width, height, quality, color, shadow, transparency, ground, mirroring. يمكن دمج جميع الخيارات بحرية (على سبيل المثال، ?color=wine_red&shadow=true&format=webp&width=1200). المجموعة الكاملة المفلترة حسب الخطة موجودة في /api/options.

ألوان الطلاء

يمكن إعادة طلاء السيارات حسب الطلب، حيث تبقى الانعكاسات، الكروم، الزجاج والداخلية دون تغيير، فقط الطلاء يتغير، وهو مطابق لملمسه (صلب أو معدني). /api/colors يسرد الكتالوج بأكمله على شكل أزواج { color_name, color_make }: الألوان الأساسية (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") متاحة على كل سيارة. الألوان الخاصة بالعلامة التجارية (على سبيل المثال، Kia *Racing Red*) تخص سيارات تلك العلامة التجارية. نقطة نهاية الألوان الخاصة بالسيارة (/colors) تسرد ما يتم عرضه لها (الألوان الأساسية + ألوان العلامة التجارية الخاصة بها). يمكن طلب أي لون نشط في الكتالوج على أي سيارة عبر ?color=. التفاصيل: دليل *ألوان الطلاء* في /info/guides/colors.

الظلال، الشفافية، والتكوين

تتم إنتاج ظلال الأرض في الاستوديو (shadow=true)، وقطع شفافة (transparency=true) وتوصيل غير شفاف أبيض في وقت التوصيل لكل رؤية خارجية، حيث تكون التوفر متسقًا في جميع أنحاء الكتالوج.

ملاحظات الأخطاء (غير قاتلة)

إذا لم يتمكن طلب من الخدمة بشكل دقيق، فلن يفشل الـ API، بل ينزلق إلى القيمة الصحيحة الأقرب ويضيف رمزًا قصيرًا إلى مصفوفة errornotes (على سبيل المثال، Y01 = السنة الأقرب المستخدمة، S05 = ظل غير متوفر). قائمة كاملة في /api/errornotes.

توصيل الصور وتخزينها المؤقت

يشير الرابط المردود image_url إلى CDN، ويحمل توقيعًا بالإضافة إلى تاريخ انتهاء الصلاحية، وهو مقفل على التحويل الدقيق. لا يمكن للعميل التلاعب به. تقوم الطلب الأول بتقديم الصورة وتخزينها في ذاكرة التخزين المؤقت؛ يتم تقديم كل طلب لاحق مباشرة من الذاكرة المؤقتة. فقط ضع الرابط في <img src>.

أرقام الحالة

• 200 — نجاح. تحقق دائمًا من errornotes للعودة الصامتة.
• 401 — عدم وجود أو عدم صحة x-api-key.
• 403 — لا يسمح لك الخطة بالوظيفة أو التنسيق أو العلامة التجارية المطلوبة.
• 404 — لا توجد بيانات لهذا المسار. الرسالة تحدد بالضبط ما يجب فحصه.

التقاليد

• أسماء العلامة التجارية / النموذج / التغير / التجهيز غير حساسة لحالة الحروف وتقبل التسميات الشائعة.
• سنوات النموذج تتوافق مع الجيل المتاح الأقرب.
• تعيد نقاط نهاية القائمة بيانات JSON؛ تأتي بايتات الصورة فقط من image_url الموقعة.