POST /v1/analyze

Analiza imágenes de neumáticos y vehículos mediante IA avanzada para identificar la marca, el modelo, el año, los acabados (trims) y las especificaciones de los neumáticos del vehículo.

Endpoint

POST https://api.ruedalens.com/v1/analyze

Autenticación

Requiere una clave de API válida en la cabecera Authorization.

Authorization: Bearer rdlns_sk_...

Modos de reconocimiento

La API soporta dos modos de reconocimiento, seleccionables por solicitud mediante el parámetro mode:

La respuesta siempre incluye un campo mode confirmando qué modo se utilizó.

Solicitud

Cabeceras

Parámetros del cuerpo

Ejemplo de solicitud

curl -X POST https://api.ruedalens.com/v1/analyze \
  -H "Authorization: Bearer rdlns_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "single",
    "image": "/9j/4AAQSkZJRg..."
  }'

Respuesta

Éxito — 200 OK

{
  "success": true,
  "requestId": "cmlecazi4000111qu590n9v6i",
  "mode": "dual",
  "data": {
    "vehicles": [
      {
        "confidence": 0.98,
        "brand": "Lexus",
        "model": "NX",
        "trims": ["300h", "300"],
        "start_year": 2017,
        "end_year": 2021,
        "current_tire": {
          "tire_brand": "Bridgestone",
          "tire_model": "Dueler H/L 33",
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": null,
          "xl": null,
          "3pmsf": null,
          "tire_size": "225/60R18 100H"
        },
        "oe_front_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false,
          "tire_size": "225/60R18 100H"
        },
        "oe_rear_tire": {
          "width": 225,
          "aspect_ratio": 60,
          "diameter": 18,
          "load_index": "100",
          "speed_index": "H",
          "structure": "R",
          "runflat": false,
          "xl": false,
          "tire_size": "225/60R18 100H"
        },
        "pressure_front": 2.2,
        "pressure_rear": 2.2
      }
    ]
  },
  "metrics": {
    "executionTimeMs": 10364
  },
  "timestamp": "2026-02-08T22:54:03.962Z"
}

Campos de la respuesta

Estructura del objeto de neumático

Cada objeto de neumático (current_tire, oe_front_tire, oe_rear_tire) contiene los campos siguientes. Los campos tire_brand y tire_model son exclusivos de current_tire y no están presentes en los objetos de neumáticos OE.

Comprendiendo los campos de neumáticos

La respuesta incluye tres especificaciones de neumáticos con distintos propósitos:

• current_tire: Especificación leída del flanco del neumático mediante OCR. Representa lo que está montado actualmente. Puede contener valores null si el texto no es legible.
• oe_front_tire: Especificación original de fábrica (OE) del eje delantero según el fabricante.
• oe_rear_tire: Especificación original de fábrica (OE) del eje trasero. En la mayoría de vehículos coincide con la delantera salvo configuraciones escalonadas.

Comprendiendo los niveles de confianza

El campo confidence (0.0 a 1.0) indica el grado de certeza de la IA en la identificación del vehículo:

Comprendiendo el array de acabados (trims)

El array trims está ordenado por probabilidad, siendo el primero el más probable:

"trims": ["300h", "300", "200t"]

Esto indica que el vehículo es más probablemente un "300h", aunque también podría ser un "300" o un "200t". Usa el primer valor como coincidencia principal.

Respuestas de error

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Invalid request body",
    "details": {
      "field": "tireImage",
      "issue": "Must be a valid base64-encoded image"
    }
  }
}

422 Imagen no legible

Se devuelve cuando la imagen es válida pero su contenido no permite una extracción fiable del tamaño del neumático (p. ej., no es un neumático, solo se ve la banda de rodadura, marcajes del flanco ilegibles).

{
  "success": false,
  "error": {
    "code": "UNREADABLE_IMAGE",
    "message": "Only the tire tread is visible. The sidewall markings where the tire size is printed cannot be read."
  }
}

Consulta UNREADABLE_IMAGE para más detalles.

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

429 Too Many Requests

Se devuelve como RATE_LIMIT_EXCEEDED para límites de ráfaga, o QUOTA_EXCEEDED para agotamiento de cuota mensual (plan Sandbox):

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded"
  }
}

Requisitos de las imágenes

Guías de calidad de imagen

La calidad de las imágenes de entrada afecta directamente a la precisión. Sigue estas recomendaciones para obtener los mejores resultados:

Buenas prácticas para la imagen del neumático

• Iluminación: Luz uniforme sin sombras duras sobre el texto del flanco
• Ángulo: Foto perpendicular a la rueda (frontal, sin inclinación)
• Enfoque: Todo el texto del flanco debe verse nítido y legible
• Cobertura: Captura completa del marcado del neumático (p. ej., "225/60 R18 100H")
• Evitar: Imágenes borrosas, ángulos extremos, sombras intensas o texto obstruido

Buenas prácticas para la imagen del vehículo

• Encuadre: Incluye el vehículo completo (frontal tres cuartos, lateral o trasero funcionan mejor)
• Distancia: Colócate a 3–5 metros para un encuadre óptimo
• Claridad: El diseño y las líneas de la carrocería deben verse claramente
• Evitar: Primeros planos extremos, vehículos cortados o imágenes muy recortadas

Ejemplos visuales

A continuación se muestran ejemplos reales que demuestran una captura adecuada para obtener resultados óptimos.

Ejemplo 1: Condiciones estándar

Imagen del neumático: ángulo perpendicular, iluminación uniforme y texto legible

Imagen del vehículo: vista completa con líneas y elementos de diseño claros

Ejemplo 2: Condiciones difíciles

Nuestro sistema mantiene alta precisión incluso en condiciones menos ideales:

Neumático con barro: el sistema extrae correctamente las especificaciones

Imagen del vehículo: condiciones exigentes que demuestran la robustez del reconocimiento

Rendimiento y facturación

Tiempo de procesamiento

Tiempo de respuesta típico de extremo a extremo: 7–15 segundos

Incluye:

• Tiempo de red: Subida de imágenes a nuestros servidores (~1–3 s según conexión y tamaño)
• Procesamiento en servidor: Análisis y enriquecimiento mediante IA (~7–10 s)
• Tiempo de red: Descarga de la respuesta (<1s)

Factores que afectan al tiempo de procesamiento:

El métrico executionTimeMs:

• Refleja solo el tiempo de procesamiento en servidor (excluye red)
• Útil para monitorizar tendencias de rendimiento
• Suele oscilar entre 10.000 ms y 20.000 ms

Cuota y facturación

• Cada solicitud cuenta para tu cuota mensual, tenga éxito o falle
• Pueden devolverse múltiples coincidencias cuando la confianza se reparte entre modelos similares
• La API procesa ambas imágenes simultáneamente para máxima precisión