Empezar

API de Vehicle Imagery v1.2.0

Imágenes de autos de calidad de estudio para cada marca, modelo, año, variante, acabado y vista — entregadas como URLs de CDN firmadas con formato, tamaño, relación de aspecto, color de pintura, sombra, transparencia, anclaje y reflejo en el piso a la demanda.

URL base

Todos los puntos finales están en vivo bajo https://api.vehicleimagery.com.

Autenticación

Cada solicitud necesita su clave API en el encabezado x-api-key:

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

Qué puede hacer tu clave (formatos, relaciones, características, marcas) se devuelve por /api/me. Los endpoints de documentación (/api/openapi.json, /api/docs) son públicos y no necesitan clave.

Cómo funciona

Navega el catálogo hasta llegar a un solo coche: marca → modelo → año → variante → acabado → vista, por ejemplo, GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
Resuelve una imagen añadiendo la vista + opciones: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → devuelve metadatos más una image_url firmada.
Incrusta image_url directamente en tu <img>. Está firmado y bloqueado de transformaciones; los bytes se generan en la primera solicitud y se almacenan en caché en el CDN durante el TTL de tu plan (por defecto 7 días).

Complemento de API v2: sets de estudio, giros de 360° y estilo de vida (nuevo)

Las claves con el complemento API v2 también incluyen nuestros nuevos conjuntos de imágenes de estudio — en el mismo catálogo y con las mismas llamadas. Verifica access en /api/me: v1 = imágenes estándar, v2 = complemento, all = ambos. En el punto final de la configuración, un coche con imágenes de complemento lista groups junto a views:

Vistas estándar (front, front_left … right) — mismas URLs de siempre.
Grupos de estudio …/{trim}/{group} lista las imágenes, …/{trim}/{group}/{image} resuelve una.
hero — tomas heroicas, vistas tres cuartos, algunas desde el nivel del suelo (8 imágenes)
steered — ruedas delanteras giradas, desde tres alturas de cámara (8 imágenes)
extra — más ángulos: cada lado y esquina a nivel de los ojos, alto y bajo, esquinas también a 30° y 45° (56 imágenes)
drone — desde arriba: tomas en ángulo, vistas elevadas y directamente desde arriba (7 imágenes)
Los nombres de las imágenes indican la posición de la cámara: el lado (front, front_left, left, rear_right …) más _eye (a la altura de los ojos), _high (desde arriba), _low (bajo), _ground (a nivel del suelo), _30 / _45 (vista en esquina a 30° / 45°), _steep (en picado desde arriba) o top (de arriba abajo). La cantidad de números por coche puede variar; /api/getall y el endpoint del grupo los muestran.
Giros de 360° — …/{trim}/360 enumera los anillos (eye_level, low, high), …/{trim}/360/{ring} devuelve cada fotograma con su propio image_url (un giro necesita todos ellos, en orden).
Escenas de estilo de vida: …/{trim}/lifestyle lista las escenas, …/lifestyle/{scene} sus imágenes, …/lifestyle/{scene}/{image} resuelve una.

Cada punto final de referencia conoce el complemento: /api/search y /api/getall incluyen autos del complemento (getall con sus groups), los /colors, /features y /all de un auto describen sus opciones del complemento, y /api/options, /api/sizes, /api/views y /api/me añaden una sección addon. Todo también funciona por id estable (/api/id/{id}/…).

Las imágenes adicionales aceptan opciones extra: lights, background (blanco, transparente o cualquier hex), color como hex (por ejemplo, c8102e), windows=dark, plate (blank o su logo), fit, size y hotspots — vea *Resolver una URL de imagen firmada*. Sin el complemento, estos parámetros se ignoran y no se listan grupos.

Nombres e ids: todos los coches, estándar y adicionales, utilizan la misma nomenclatura del catálogo (por ejemplo, Mercedes-Benz / C-Class, BMW / 5 series). Los nombres utilizados antes del 5 de octubre de 2026 (por ejemplo, Mercedes / C-Klasse) aún se resuelven y responden con el nombre actual. Los nombres nunca contienen una barra: donde el catálogo escribe una, el nombre tiene un guión (por ejemplo, Chevrolet / C-K). Los coches que solo existen en el adicional tienen ids a partir de 900000000; /api/id/{id}/… funciona para ellos como para cualquier otro coche.

¿Tienes un vehículo real? (Beta)

Si conoces el VIN o la matrícula del coche en lugar de su posición en el catálogo, los complementos de búsqueda hacen ambos pasos en una sola llamada: GET /vin/{vin} y GET /plate/{plate} decodifican el vehículo y devuelven la coincidencia más cercana del catálogo con URLs de imágenes firmadas junto a los datos decodificados. Ambos son optativos por clave — revisa features.vin y features.plate en /api/me. Sin el complemento, devuelven 403.

Opciones de imagen

Agregue a cualquier solicitud de imagen: format, resolution, ratio, width, height, quality, color, shadow, transparency, ground, mirroring. Todas las opciones se combinan libremente (por ejemplo, ?color=wine_red&shadow=true&format=webp&width=1200). El conjunto completo filtrado por plan está en /api/options.

Colores de pintura

Los autos pueden ser repintados bajo demanda: los reflejos, el cromo, el vidrio y el interior permanecen intactos; solo cambia la pintura, fiel a su acabado (sólido o metálico). /api/colors lista todo el catálogo como pares { color_name, color_make }: los colores de la casa (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") están disponibles en todos los autos; los colores de la marca (por ejemplo, Kia *Racing Red*) pertenecen a los autos de esa marca. El endpoint /colors de un auto lista lo que se muestra para él (colores de la casa + los colores de su marca) — cualquier color del catálogo activo aún puede ser solicitado en cualquier auto a través de ?color=. Detalles: la guía *Colores de pintura* en /info/guides/colors.

Sombras, transparencia y composición

Las sombras de suelo de estudio (shadow=true), los recortes transparentes (transparency=true) y la entrega opaca blanca se producen en el momento de la entrega para cada vista exterior. La disponibilidad es uniforme en todo el catálogo.

Notas de error (no fatales)

Cuando una solicitud no puede ser atendida exactamente, la API no falla. En su lugar, recurre al valor válido más cercano y añade un código breve al array errornotes (por ejemplo, Y01 = año más cercano utilizado, S05 = sombra no disponible). La lista completa está en /api/errornotes.

Entrega y almacenamiento en caché de imágenes

La image_url devuelta apunta al CDN, lleva una firma más una fecha de caducidad, y está bloqueada a la transformación exacta, los clientes no pueden manipularla. La primera solicitud produce y almacena en caché los bytes, cada solicitud posterior se sirve directamente desde la caché. Solo hay que colocar la URL en un <img src>.

Las nuevas imágenes se producen en una cola justa: los planes con mayor prioridad van primero, y las solicitudes idénticas que llegan al mismo tiempo se producen una sola vez. La primera carga de una nueva combinación generalmente tarda unos segundos; la cabecera de respuesta X-Cache le indica de dónde proviene (MISS = recién producida, HIT / HIT-R2 = caché, ORIGINAL = archivo fuente sin modificar), X-Queue-Wait-Ms cuánto tiempo esperó. Si se están produciendo un gran número de nuevas imágenes al mismo tiempo, una URL de imagen puede responder 503 busy con Retry-After: 5, simplemente cargue la imagen de nuevo unos segundos después.

Códigos de estado

200 — éxito. Siempre revise errornotes para fallos silenciosos.
401 — falta o es inválida x-api-key.
403 — su plan no permite la característica, formato o marca solicitada.
404 — no hay datos para esa ruta. El mensaje nombra exactamente qué revisar.
503 — (solo URLs de imágenes) se están produciendo muchas imágenes nuevas en este momento; vuelva a intentarlo después de los segundos en Retry-After.

Convenciones

Los nombres de marca/modelo/variante/acabado no distinguen entre mayúsculas y minúsculas y aceptan alias comunes.
Los años se ajustan a la generación disponible más cercana.
Los endpoints del catálogo devuelven JSON; los bytes de imagen solo provienen de la image_url firmada.