De la foto a los datos del alimento: los endpoints de visión

Cuatro cosas en las que se puede convertir una foto

Los endpoints de visión convierten una foto en datos de alimentos estructurados. Hay cuatro modos, cada uno con su propio endpoint y su precio en créditos de IA (todos los planes — incluido Free — incluyen una asignación mensual):

Endpoint	Qué hace	Créditos
POST /v1/vision/barcode	Decodifica un código de barras desde una foto y devuelve el producto encontrado	0 (usa tu cuota diaria)
POST /v1/vision/product	Reconoce un producto a partir de la foto de su frontal	3
POST /v1/vision/label	Lee una etiqueta nutricional: tabla, ingredientes, alérgenos	4
POST /v1/vision/meal	Identifica los platos de un plato con estimaciones de porción	5

La decodificación de códigos de barras es visión por computador pura — no interviene ningún modelo de IA — por eso no consume créditos y se mide como una petición de datos normal.

Puedes probar los cuatro en el navegador, con tu propia clave y tus propias fotos, en el playground de fotos.

La forma de la petición

Los cuatro reciben la misma petición multipart — un único campo image:

curl -X POST "https://foodbase.dev/v1/vision/product" \
  -H "X-API-Key: food_your_key_here" \
  -F "[email protected]"

O desde JavaScript:

async function vision(endpoint, file) {
  const form = new FormData();
  form.append("image", file);
  const res = await fetch(`https://foodbase.dev/v1/vision/${endpoint}`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (!res.ok) throw new Error(`Vision error: ${res.status}`);
  return res.json();
}

Las fotos se normalizan en el servidor (se reducen y se elimina el EXIF) antes de que nada llegue a un modelo de IA, y las imágenes nunca se almacenan — la foto se analiza y se descarta.

Reconocimiento de productos

/vision/product extrae lo que el modelo puede ver y lo compara con el catálogo de 6,1 M de productos, devolviendo coincidencias ordenadas por puntuación:

{
  "request_id": "…",
  "cached": false,
  "extracted": {
    "name": "Масло Краве",
    "brand": "…",
    "quantity": "250 g",
    "lang": "bg",
    "confidence": 0.95
  },
  "matches": [
    { "score": 0.98, "product": { "id": "…", "name_default": "…", "nutrition_summary": { } } }
  ]
}

También lee envases en alfabetos no latinos — las etiquetas en cirílico llegan a las entradas correctas del catálogo. Trata matches[0] como la respuesta cuando su puntuación sea alta, y muestra una lista corta para elegir cuando varias coincidencias tengan puntuaciones parecidas.

Lectura de etiquetas

/vision/label aplica OCR a un panel nutricional y lo devuelve con los mismos nombres de campo que usa el resto de la API — más el texto de los ingredientes y los alérgenos detectados:

{
  "extracted": {
    "energy_kcal": 539,
    "fat_g": 30.9,
    "saturated_fat_g": 10.6,
    "carbs_g": 57.5,
    "sugars_g": 56.3,
    "proteins_g": 6.3,
    "salt_g": 0.11,
    "ingredients_text": "Sugar, palm oil, hazelnuts 13%…",
    "allergens": ["milk", "nuts"],
    "product_name": "Nutella",
    "confidence": 0.97
  },
  "product": { "id": "…" }
}

Los campos que la etiqueta no muestra vuelven como null — el modelo nunca inventa números. Si la etiqueta incluye un código de barras o el producto se reconoce, product enlaza con el registro del catálogo.

Análisis de comidas

/vision/meal identifica los platos de un plato, estima las porciones y asocia cada plato con un alimento genérico para darte estimaciones de calorías:

{
  "items": [
    {
      "dish": "grilled chicken breast",
      "portion_g_est": 150,
      "confidence": 0.9,
      "match": {
        "name_default": "Chicken breast, grilled",
        "per_100g": { "energy_kcal": 165, "proteins_g": 31, "carbs_g": 0, "fat_g": 3.6 },
        "estimated_kcal": 248
      }
    }
  ],
  "estimated_total_kcal": 612,
  "disclaimer": "Dish identification and portion sizes are AI estimates from a photo…"
}

Las porciones a partir de una sola foto son estimaciones — la respuesta lo indica en disclaimer, y tu interfaz también debería hacerlo, idealmente con una forma rápida de que el usuario ajuste los gramos.

Créditos, caché y errores

• Cada respuesta de IA incluye las cabeceras X-Credits-Limit, X-Credits-Remaining y X-Credits-Reset — muéstralas en tu app para que los usuarios nunca se lleven sorpresas.
• Las imágenes idénticas se guardan en caché en el servidor, así que las peticiones repetidas devuelven al instante — al mismo precio en créditos. Diseña tu app para guardar los resultados en caché en el cliente en lugar de volver a enviar la misma foto.
• No se te cobra cuando la petición falla: imágenes inválidas o demasiado grandes, errores del proveedor y códigos de barras no encontrados se reembolsan automáticamente.
• Espera y gestiona 402 (sin créditos), 429 (límite de visión por segundo — todos los planes tienen uno) y 413 (imagen demasiado grande).

Por dónde empezar

Juega con tus propias fotos en el playground y luego lee los contratos completos de petición/respuesta en la documentación. Los 20 créditos mensuales del plan gratuito bastan para probar los cuatro modos una vez.