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

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

رابط أساسي

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

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

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

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

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

كيف يعمل ذلك

1. استكشف الفهرس حتى تصل إلى سيارة واحدة: brand → model → year → variant → trim → view، على سبيل المثال، 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 أيام).

هل لديك سيارة حقيقية؟ *(Beta)*

إذا كنت تعرف رقم VIN أو تسجيل السيارة بدلاً من موقعها في الكتالوج، فإن إضافات البحث تقوم بخطوتين في مكالمة واحدة: GET /vin/{vin} و GET /plate/{plate} تقرأ السيارة وتعيد أقرب مطابقة في الكتالوج مع روابط صور معتمدة بجانب البيانات المشفرة. كلاهما اختياري لكل مفتاح — تحقق من features.vin و features.plate في /api/me؛ بدون الإضافة، تعودان 403.

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

أضف إلى أي طلب صور: 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 يشير إلى الشبكة، يحمل توقيعًا بالإضافة إلى تاريخ انتهاء الصلاحية، وهو مقفل على التحويل الدقيق — العملاء لا يمكنهم التلاعب به. الطلب الأول يعرض ويخزن البايتات، كل طلب لاحق يتم تقديمه مباشرة من المخزن المؤقت. فقط ضع الرابط في <img src>.

أكواد الحالة

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

التقاليد

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