واجهة برمجة تطبيقات Vehicle Imagery v1.2.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 أيام).

إضافة API v2: مجموعات الاستوديو، دوارات 360° وحياة *(جديد)*

المفاتيح التي تحتوي على إضافي API v2 تحصل أيضًا على مجموعات الصور الجديدة في الاستوديو — في نفس الكتالوج وبنفس المكالمات. تحقق من access في /api/me: v1 = صور قياسية، v2 = إضافي، all = كلاهما. في نهاية التجهيز، يسرد سيارة تحتوي على صور إضافية groups بجانب views:

• المناظر القياسية (front, front_left … right) — نفس الروابط دائمًا.
• مجموعات الاستوديو، …/{trim}/{group} تدرج الصور، …/{trim}/{group}/{image} تحل واحدة:
• hero صور رئيسية، زوايا ثلاثة أرباع، بعضها من مستوى الأرض (8 صور)
• steered عجلات الأمامية موجهة، من ثلاثة ارتفاعات للكاميرا (8 صور)
• extra زوايا إضافية: كل جانب وزاوية من مستوى العين، من الأعلى ومن الأسفل، زوايا إضافية عند 30° و45° (56 صورة)
• drone من الأعلى: صور مائلة، زوايا حادة، ومن الأعلى مباشرة (7 صور)
• أسماء الصور تشير إلى موقع الكاميرا: الجانب (front، front_left، left، rear_right …) بالإضافة إلى _eye (مستوى العين)، _high (من فوق)، _low (من أسفل)، _ground (على مستوى الأرض)، _30 / _45 (رؤية الزاوية عند 30° / 45°)، _steep (من أعلى بشكل حاد) أو top (من أعلى مباشرة). يمكن أن تختلف الأرقام لكل سيارة؛ /api/getall ونهاية المجموعة تظهرها.
• دوران 360° — …/{trim}/360 يسرد الحلقات (eye_level، low، high)، …/{trim}/360/{ring} يعيد كل إطار مع image_url الخاص به (يحتاج الدوران إلى جميعها، بترتيب).
• مواقف نمط الحياة: …/{trim}/lifestyle يسرد المواقف، …/lifestyle/{scene} صورها، …/lifestyle/{scene}/{image} يحل صورة واحدة.

كل نقاط النهاية المرجعية تعرف الإضافة: /api/search و /api/getall تشمل السيارات الإضافية (getall مع groups)، و /colors و /features و /all يصفون خيارات الإضافة للسيارة، و /api/options و /api/sizes و /api/views و /api/me يضيف قسم addon. كل شيء يعمل أيضًا بواسطة معرف ثابت (/api/id/{id}/…).

تتيح صور الإضافات خيارات إضافية: lights، background (أبيض، شفاف أو أي كود سداسي)، color كود سداسي (على سبيل المثال، c8102e)، windows=dark، plate (blank أو logo الخاص بك)، fit، size و hotspots — انظر *حلل عنوان صورة موقعة*. بدون الإضافات، يتم تجاهل هذه المعاملات ولا يتم إدراج أي مجموعات.

الأسماء والأرقام التسلسلية: جميع السيارات، القياسية والمضافة، تستخدم نفس تسمية الكتالوج (على سبيل المثال، Mercedes-Benz / C-Class, BMW / 5 series). الأسماء المستخدمة قبل 5 أكتوبر 2026 (على سبيل المثال، Mercedes / C-Klasse) لا تزال تتوافق وتجيب باسم الحالي. الأسماء لا تحتوي على شريط: حيث يكتب الكتالوج شريطًا، يحتوي الاسم على شرطة (على سبيل المثال، Chevrolet / C-K). السيارات التي توجد فقط في المضافة لها أرقام تسلسلية من 900000000؛ /api/id/{id}/… يعمل لها كما هو الحال مع أي سيارة أخرى.

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

تُنتج الصور الجديدة في قائمة انتظار عادلة: تذهب الخطط ذات الأولوية الأعلى أولاً، وتُنتج الطلبات المتطابقة التي تصل في نفس الوقت مرة واحدة. عادةً ما يستغرق أول تحميل لمزيج جديد بضع ثوانٍ، ويخبرك رأس الرسالة X-Cache عن مصدرها (MISS = تم إنتاجها الآن، HIT / HIT-R2 = مخزن مؤقت، ORIGINAL = ملف مصدر لم يتم لمسه)، X-Queue-Wait-Ms كم من الوقت انتظرت. إذا كان يتم إنتاج عدد كبير جدًا من الصور الجديدة في نفس الوقت، يمكن أن يجيب رابط الصورة 503 busy مع Retry-After: 5، فقط قم بتحميله مرة أخرى بعد بضع ثوانٍ.

أكواد الحالة

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

التقاليد

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