Referencia de la API v1

Documentación

Todo lo que necesita para integrar imágenes de vehículos de calidad de estudio en su aplicación.

Inicio / Documentación

/ autenticación /

Autenticación con API Key

Todas las solicitudes a la API requieren una API key enviada a través del header x-api-key. Puede obtener su clave a través de nuestro panel de control o contactando al equipo de ventas.

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

Mantenga su API key en secreto. Nunca la exponga en código del lado del cliente. Use solicitudes del lado del servidor o un proxy para mantener su clave segura.

/ base url /

Base URL

Todos los endpoints de la API se acceden en relación con la siguiente base URL:

api.vehicleimagery.com

Todas las respuestas se devuelven como JSON con Content-Type: application/json. CORS está habilitado para todos los orígenes.

/ parámetros /

Parámetros de consulta globales

Estos parámetros se pueden agregar a la mayoría de los endpoints para filtrar resultados.

Parámetro Predeterminado Descripción
format png Formato de imagen. Las opciones disponibles dependen de su plan.
resolution default Resolución de imagen. Las resoluciones más altas pueden requerir un plan de nivel superior.
color default Color del vehículo. Solo se utiliza en el endpoint de imagen.
shadow false Agregar sombra de suelo a la imagen. Requiere permiso del plan.
transparency false Devolver imagen con fondo transparente. Requiere permiso del plan.

/ modelo de datos /

Jerarquía de la API

La API de Vehicle Imagery sigue una estructura jerárquica. Navegue paso a paso desde la marca hasta la imagen:

Marcas → Modelos → Años → Variantes → Acabados → Vistas / Colores / Características → Imagen
GET /api/brands

Listar marcas

Devuelve todas las marcas de vehículos disponibles en la base de datos.

Parámetros de consulta

format = png Filtro de formato de imagen (png, webp, etc.)
resolution = default Filtro de resolución (default, high, etc.)

Respuesta de ejemplo

response.json 
{
  "brands": [
    "Audi",
    "BMW",
    "Mercedes-Benz",
    "Volkswagen",
    ...
  ]
}
GET /api/{brand}

Listar modelos

Devuelve todos los modelos disponibles para una marca determinada.

Parámetros de ruta

brand string Nombre de la marca (ej. BMW, Audi)

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
{
  "brand": "BMW",
  "resolution": "default",
  "format": "png",
  "models": [
    "1 Series",
    "3 Series",
    "X5",
    ...
  ]
}
GET /api/{brand}/{model}

Listar años

Devuelve todos los años de modelo disponibles para una combinación específica de marca y modelo.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo (ej. X5, A4)

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "resolution": "default",
  "format": "png",
  "years": [2020, 2021, 2022, 2023, 2024]
}]
GET /api/{brand}/{model}/{year}

Listar variantes

Devuelve todas las variantes de carrocería (ej. Sedán, SUV, Wagon) disponibles para un año de modelo específico.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo (ej. 2024)

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "resolution": "default",
  "format": "png",
  "variants": ["SUV"]
}]
GET /api/{brand}/{model}/{year}/{variant}

Listar acabados

Devuelve todos los acabados disponibles para una variante específica.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo
variant string Variante de carrocería (ej. SUV, Sedán)

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "resolution": "default",
  "format": "png",
  "trims": ["xDrive40i", "M60i"]
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}

Listar vistas

Devuelve todos los ángulos de cámara/vistas disponibles para una configuración de vehículo específica. Las vistas marcadas como "not_allowed" no están incluidas en su plan actual.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo
variant string Variante de carrocería
trim string Nivel de acabado

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "views": {
    "front": true,
    "front-left": true,
    "side-left": true,
    "rear": true,
    "cockpit": "not_allowed"
  }
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/colors

Listar colores

Devuelve todos los colores disponibles para una configuración de vehículo específica. Solo se incluyen los colores permitidos por su plan.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo
variant string Variante de carrocería
trim string Nivel de acabado

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "colors": ["default", "Blue", "Black", "White", "Silver"]
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/features

Listar características

Devuelve las características de imagen disponibles (sombra, transparencia) para una configuración. Las características marcadas como "not_allowed" no están incluidas en su plan.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo
variant string Variante de carrocería
trim string Nivel de acabado

Parámetros de consulta

format = png Filtro de formato de imagen
resolution = default Filtro de resolución

Respuesta de ejemplo

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "features": {
    "shadow": true,
    "transparent": true,
    "shadow_and_transparent": true
  }
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/{view}

Obtener imagen

Devuelve una URL de CDN firmada para una imagen de vehículo específica. Este es el endpoint principal para obtener imágenes de vehículos. La URL devuelta es válida por 7 días de forma predeterminada.

Parámetros de ruta

brand string Nombre de la marca
model string Nombre del modelo
year number Año del modelo
variant string Variante de carrocería
trim string Nivel de acabado
view string Ángulo de cámara (ej. front, front-left, side-left, rear, cockpit)

Parámetros de consulta

format = png Formato de imagen (png, webp)
resolution = default Resolución de imagen
color = default Color del vehículo (ej. Blue, Black, White)
shadow = false Incluir sombra de suelo (depende del plan)
transparency = false Fondo transparente (depende del plan)

Respuesta de ejemplo

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "view": "front-left",
  "resolution": "default",
  "format": "png",
  "settings": {
    "color": "Blue",
    "shadow": true,
    "transparency": false,
    "watermark": false
  },
  "image_url": "https://cdn.vehicle.pics/v1/png/default/BMW/X5/...",
  "errornotes": []
}]
GET /api/resolutions

Listar resoluciones

Devuelve todas las resoluciones de imagen disponibles. Filtrado según los permisos de su plan.

Respuesta de ejemplo

response.json 
{
  "resolutions": ["default", "high", "ultra"]
}
GET /api/formats

Listar formatos

Devuelve todos los formatos de imagen disponibles. Filtrado según los permisos de su plan.

Respuesta de ejemplo

response.json 
{
  "formats": ["png", "webp"]
}
GET /api/getall

Obtener todas las configuraciones

Devuelve cada configuración de vehículo en la base de datos, expandida por año. Requiere el permiso especial "getall" en su API key. Útil para construir cachés locales o catálogos.

Respuesta de ejemplo

response.json 
[
  {
    "brand": "BMW",
    "model": "X5",
    "variant": "SUV",
    "trim": "xDrive40i",
    "year": 2024,
    "resolution": "default",
    "format": "png",
    "color": "default"
  },
  ...
]

/ referencia /

Códigos de estado HTTP

La API utiliza códigos de estado HTTP estándar. Cada respuesta de error incluye un cuerpo JSON con un campo error que describe el problema.

Código Descripción
401 Falta el header x-api-key. Incluya su API key en la solicitud.
403 API key inválida, clave expirada, o el recurso solicitado no está permitido por su plan.
404 La marca, modelo, año, variante, acabado, vista o color solicitado no fue encontrado.
400 Parámetro de solicitud inválido (ej. año no numérico).
500 Error interno del servidor. Contacte a soporte si esto persiste.

Notas de error (Códigos de respaldo)

Cuando la API no puede cumplir su solicitud exacta pero encuentra un respaldo adecuado, devuelve la imagen junto con un array errornotes que explica lo que se cambió. Esto solo aplica cuando los respaldos están habilitados en su plan.

Código Descripción
P11 Formato o resolución solicitados no permitidos por el plan — se utilizó automáticamente el valor predeterminado de su plan.
F04 Color solicitado no encontrado — se utilizó el color predeterminado.
C09 Color solicitado bloqueado por el plan — se utilizó el color predeterminado.
R08 Resolución solicitada no disponible para este vehículo — se utilizó la resolución permitida más cercana.
S05 Sombra solicitada pero no disponible o no permitida — devuelto sin sombra.
S12 Versión sin sombra no disponible — se devolvió la versión con sombra.
T06 Transparencia solicitada pero no disponible o no permitida — devuelto sin transparencia.
T13 Versión no transparente no disponible — se devolvió la versión transparente.

Límites de solicitudes y caché

Los límites de solicitudes dependen de su plan. Todas las URLs de imágenes se sirven a través de un CDN global y están firmadas con un token de tiempo limitado (7 días por defecto). Almacene estas URLs en caché para un rendimiento óptimo.

50ms

Latencia prom.

99.99

SLA de disponibilidad

7 Days

Expiración de URL

¿Listo para comenzar?

Obtenga su API key y comience a integrar imágenes de vehículos de calidad de estudio hoy.

Obtener API Key Contactar ventas