Vehicle Imagery API v1.2.0

हर ब्रांड, मॉडल, साल, वेरिएंट, ट्रिम और व्यू के लिए स्टूडियो-क्वालिटी कार इमेज — साइन किए गए CDN URLs के रूप में डिलीवरी की जाती है, जिसमें ऑन-द-फ्लाई फॉर्मेट, साइज, एस्पेक्ट-रेशियो, पेंट कलर, शैडो, ट्रांसपेरेंसी, ग्राउंडिंग और फ्लोर-मिररिंग।

बेस URL

सभी एंडपॉइंट्स 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. Embed image_url सीधे अपने <img> में। यह साइन किया गया और ट्रांसफॉर्म-लॉक किया गया है; बाइट्स पहले अनुरोध पर उत्पन्न होते हैं और CDN पर आपके प्लान के TTL के लिए कैश किए जाते हैं (डिफ़ॉल्ट 7 दिन)।

एपीआई वी2 एड-ऑन: स्टूडियो सेट, 360° स्पिन और लाइफस्टाइल (नया)

API v2 add-on के साथ कीज भी हमारी नई स्टूडियो इमेज सेट्स पाते हैं — उसी कैटलॉग में और उन्हीं कॉल्स के साथ। access को /api/me में देखें: v1 = स्टैंडर्ड इमेज, v2 = add-on, all = दोनों। ट्रिम एंडपॉइंट पर add-on इमेज के साथ एक कार groups को views के साथ सूचीबद्ध करता है।

• मानक दृश्य (front, front_left … right) — वही URLs जैसे हमेशा.
• स्टूडियो समूह …/{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. *एक साइन किए गए छवि URL को सुलझाएं* देखें। एड-ऑन के बिना ये पैरामीटर अनदेखे जाते हैं और कोई समूह सूचीबद्ध नहीं किया जाता।

नाम और आईडी: सभी कारें, मानक और अतिरिक्त, एक ही कैटलॉग नामिंग का उपयोग करती हैं (उदाहरण के लिए, 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} वाहन को डिकोड करते हैं और डिकोडेड डेटा के साथ-साथ साइन किए गए इमेज यूआरएल्स के साथ सबसे करीबी कैटलॉग मैच वापस करते हैं। दोनों की सुविधा प्रति की है — /api/me में features.vin और features.plate देखें; एड-ऑन्स के बिना वे 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= के माध्यम से मांगा जा सकता है। विवरण: *Paint colors* गाइड /info/guides/colors पर है।

शैडो, ट्रांसपेरेंसी और कॉम्पोजिटिंग

स्टूडियो ग्राउंड शैडो (shadow=true), ट्रांसपेरेंट कट-आउट (transparency=true) और ओपेक व्हाइट डिलीवरी हर एक्सटीरियर व्यू के लिए डिलीवरी टाइम पर बनाई जाती है। पूरे कैटलॉग में उपलब्धता एक समान है।

एररनोट्स (गैर-घातक)

जब एक रिक्वेस्ट को ठीक से सर्व नहीं किया जा सकता, तो API फेल नहीं होता — यह सबसे करीबी वैध मान पर फॉलबैक करता है और एक छोटी कोड को errornotes एरे में जोड़ता है (उदाहरण के लिए, Y01 = सबसे करीबी साल का उपयोग किया गया, S05 = छाया उपलब्ध नहीं)। पूर्ण सूची /api/errornotes में है।

चित्र डिलीवरी और कैशिंग

वापस किया गया image_url CDN की ओर इशारा करता है, एक सिग्नेचर और एक एक्सपायरी ले जाता है, और सही ट्रांसफ़ॉर्म पर लॉक किया जाता है — क्लाइंट इसे बदल नहीं सकते. पहला अनुरोध बाइट्स को उत्पन्न करता है और कैश करता है; हर बाद का अनुरोध सीधे कैश से सर्व किया जाता है. बस URL को एक <img src> में डालें.

नए चित्रों का उत्पादन एक न्यायोचित कतार में होता है: उच्च प्राथमिकता वाले प्लान पहले जाते हैं, और एक ही समय पर आने वाले समान अनुरोध एक बार ही बनाए जाते हैं। एक नए संयोजन का पहला लोड आमतौर पर कुछ सेकंड लेता है; रिस्पॉन्स हेडर X-Cache बताता है कि यह कहाँ से आया है (MISS = अभी बनाया गया, HIT / HIT-R2 = कैश, ORIGINAL = अस्पर्शित स्रोत फ़ाइल), X-Queue-Wait-Ms कितना इंतजार किया। अगर एक बार में बहुत सारे नए चित्रों का उत्पादन हो रहा है, तो एक चित्र URL 503 busy के साथ जवाब दे सकता है, Retry-After: 5 — बस इसे कुछ सेकंड बाद फिर से लोड करें।

स्थिति कोड

• 200 — सफलता. हमेशा errornotes के लिए चुपचाप फॉलबैक्स की जांच करें.
• 401 — x-api-key गायब या अमान्य है.
• 403 — आपका प्लान अनुरोधित फीचर, फॉर्मेट या ब्रांड की अनुमति नहीं देता.
• 404 — उस पथ के लिए कोई डेटा नहीं. संदेश ठीक-ठीक बताता है कि क्या जांचना है.
• 503 — (छवि URLs केवल) अभी बहुत सारी नई छवियाँ बनाई जा रही हैं; Retry-After में सेकंड्स के बाद दोबारा प्रयास करें.

रिवाज़

• ब्रांड / मॉडल / वेरिएंट / ट्रिम नामों को केस-इन्सेंसिटिव माना जाता है और आम एलियास स्वीकार किए जाते हैं।
• साल निकटतम उपलब्ध जनरेशन तक स्नैप होते हैं
• कैटलॉग एंडपॉइंट्स JSON रिटर्न करते हैं; इमेज बाइट्स केवल साइन किए गए image_url से आते हैं।