إضافة API v2

مجموعة استوديو: قائمة صورها

GET/api/{brand}/{model}/{year}/{variant}/{trim}/hero

إضافة API v2 — مفاتيح بوصول v2. صور مجموعة استوديو واحدة. hero تشير إلى أي مجموعة استوديو للسيارة، أي المجموعات التي تمتلكها السيارة موجودة في groups على نقطة النهاية trim.

مجموعة	ما الذي يظهره	أسماء الصور (مثال سيارة)
`hero`	صور البطل: رؤية ثلاثة أرباع، بعضها من مستوى الأرض	`front_left`, `front_left_ground`, `front_right`, `front_right_ground`, `left_ground`, `rear_left`, `rear_right`, `right_ground` (8)
`steered`	عجلات الأمامي مع دوران من ثلاثة ارتفاعات كاميرا	`front_left`, `front_left_eye`, `front_left_high`, `front_left_low`, `front_right`, … (8)
`extra`	زوايا أكثر: كل جانب وزاوية من ثلاثة ارتفاعات كاميرا، الزوايا أيضًا 30° و45°	`front_eye`, `front_high`, `front_low`, `front_left_30`, `front_left_30_eye`, `front_left_45_high`, `rear_right_45_low`, `left_eye` … (56)
`drone`	من الأعلى: صور مائلة، رؤى حادة ومن الأعلى مباشرة.	`front_left`, `front_right`, `front_steep`, `rear_left`, `rear_right`, `rear_steep`, `top` (7)

أسماء الصور تتكون من الجانب (front، front_left، left، rear_right …) بالإضافة إلى اللواحق: _eye = مستوى العين، _high = الكاميرا من فوق، _low = الكاميرا من الأسفل، _ground = على مستوى الأرض، _30 / _45 = رؤية الزاوية عند 30° / 45°، _steep = من أعلى بزاوية حادة، top = مباشرة من فوق. القائمة الدقيقة لكل سيارة موجودة دائمًا في views لهذا النهاية.

اختر صورة من views وحلها مع *حل صورة مجموعة استوديو*، على سبيل المثال، GET /api/Audi/Q9/2026/SUV/Default/hero/front_left

معاملات المسار

اسم	نوع	وصف
`brand` مطلوب	string	اسم العلامة التجارية (تحديث تسمية فهرس الإضافات)
`model` مطلوب	string	اسم النموذج.
`year` مطلوب	عدد صحيح	عام النموذج (4 أرقام). إذا كان العام الدقيق مفقودًا، يتم استخدام الجيل الأقرب المتاح (ملاحظة الخطأ `Y01`).
`variant` مطلوب	string	نوع الجسم.
`trim` مطلوب	string	مستوى القطع.

معاملات الاستعلام

اسم	نوع	وصف
`version`	string	نتائج من نسخة واحدة فقط: `v1` = صور قياسية، `v2` = إضافة API v2 (بدون العودة إلى الصور القياسية). بدونها: كل ما يسمح به مفتاحك. غير مسموح به لمفتاحك → `403`. `v1v2`

طلب

curl "https://api.vehicleimagery.com/api/bmw/m4/2024/coupe/base/hero?version=v1" \
  -H "x-api-key: YOUR_API_KEY"

200 · صور المجموعة.

[
  {
    "id": 900000003,
    "brand": "Audi",
    "model": "Q9",
    "year": 2026,
    "variant": "SUV",
    "trim": "Default",
    "group": "hero",
    "resolution": "default",
    "format": "png",
    "views": {
      "front_left": true,
      "front_left_ground": true,
      "front_right": true,
      "front_right_ground": true,
      "rear_left": true,
      "rear_right": true
    }
  }
]

401 · مفتاح `x-api-key` مفقود أو غير صالح.

{
  "error": "Invalid API key"
}

403 · قيود الخطة (الميزة أو التنسيق أو العلامة التجارية غير مسموح بها) أو طلب محظور.

{
  "error": "Mirroring is not allowed by your plan."
}

404 · لا توجد بيانات للمسار المطلوب. للمسار الخاص بالسيارة، `not_found` يسمي المستوى الذي لا يوجد، و`alternatives` يسرد ما يوجد هناك بدلاً منه.

{
  "error": "Model '9 series' not found for 'BMW' — check /api/BMW for valid models.",
  "code": "model_not_found",
  "not_found": "model",
  "alternatives": {
    "models": [
      "1 series",
      "2 series",
      "3 series",
      "4 series",
      "5 series"
    ]
  }
}