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.

Dos formas de entrada

¿Conoce el coche? Navegue por el catálogo: brand → model → year → variant → trim → view. ¿Tiene un vehículo real? Use los complementos de búsqueda — GET /vin/{vin} o GET /plate/{plate} convierten un VIN o un número de registro directamente en datos del vehículo *más* imágenes de estudio de ese coche, con su color de pintura real aplicado cuando esté disponible. Los complementos se habilitan por clave; /api/me muestra lo que puede hacer la suya.

Cómo funciona

1. 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.
2. 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.
3. 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).

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 renderiza y almacena en caché los bytes; cada solicitud posterior se sirve directamente desde la caché. Solo coloca la URL en un <img src>.

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.

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.