Análisis de productos con IA: resúmenes que tus usuarios sí leen

El problema de los datos nutricionales en bruto

La respuesta de tu API dice sugars_g: 56.3. Tu usuario quiere saber: ¿es mucho? Cerrar esa brecha — convertir números y listas de ingredientes en algo con lo que una persona pueda actuar — suele ser el punto en el que las apps de nutrición invierten mucho o tiran la toalla.

Los endpoints de análisis hacen ese paso por ti: una sola llamada devuelve un análisis breve, factual y en lenguaje claro, generado estrictamente a partir de los datos del producto. Los veredictos — qué es alto, qué es un punto positivo, qué alérgenos, qué dietas — salen de umbrales fijos y publicados que se aplican en código; la IA redacta el resumen de dos frases y lee la lista de ingredientes cuando hace falta un criterio. Sin números inventados, sin declaraciones de salud y con «desconocido» en lugar de una suposición.

Analizar un producto del catálogo

POST /v1/analyze/product recibe un food_id o un barcode (uno de los dos), cuesta 4 créditos y responde en cualquiera de los 6 idiomas:

curl -X POST "https://foodbase.dev/v1/analyze/product" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"barcode": "3017620422003", "lang": "en"}'

{
  "food_id": "…",
  "lang": "en",
  "cached": false,
  "analysis": {
    "summary": "Nutella is a hazelnut and cocoa chocolate spread from Ferrero, made mainly with sugar and palm oil. It is energy-dense and high in fat, saturated fat and sugars (56.3 g per 100 g), while being low in salt.",
    "highlights": ["Low salt (0.11 g per 100 g)"],
    "warnings": [
      "High in fat (30.9 g per 100 g)",
      "High in saturated fat (10.6 g per 100 g)",
      "High in sugars (56.3 g per 100 g)",
      "Contains palm oil"
    ],
    "allergens": { "contains": ["soy", "milk", "nuts"], "may_contain": [], "text": "Contains: soy, milk, nuts." },
    "diets": { "vegan": "no", "vegetarian": "yes", "gluten_free": "yes", "lactose_free": "no" },
    "diets_detail": {
      "vegan": { "value": "no", "basis": "allergen_tag" },
      "gluten_free": { "value": "yes", "basis": "label_claim" }
    },
    "processing_level": "ultra_processed",
    "processing_basis": "nova",
    "per_serving": "Per serving (15 g): 81 kcal · 4.6 g fat · 1.6 g saturated fat · 8.4 g sugars · 0.02 g salt · 0.9 g protein"
  },
  "disclaimer": "AI-generated from the product's label data…"
}

(Abreviado: la respuesta también incluye nutrient_levels, el diets_detail completo, nova_group y flags.) Conviene conocer algunas cosas sobre su estructura:

highlights son solo puntos positivos y warnings son solo advertencias — y un mismo tema nunca aparece en ambos. Un punto positivo significa que el producto cumple la condición de una declaración nutricional de la UE (bajo en sal: como máximo 0,3 g por 100 g; fuente de proteínas: al menos el 12 % de la energía). Una advertencia es un nivel «alto» según la FSA británica, una porción grande que supera el límite por porción de la FSA, o la presencia de cafeína, edulcorantes, alcohol o aceite de palma en los ingredientes.
allergens se lista aparte: los 14 alérgenos de la UE que declara la etiqueta, como «contiene» y «puede contener», con una frase localizada. status: "not_stated" significa que el registro no tiene datos de alérgenos — revisa el envase.
diets_detail indica de dónde sale cada respuesta: una declaración de la etiqueta, un alérgeno declarado o la lista de ingredientes. «Sin gluten» y «sin lactosa» son yes solo con una declaración en la etiqueta; una lista sin ingredientes con gluten da no_known_source, porque un producto no certificado aún puede estar contaminado. diets mantiene la vista sencilla yes / no / unknown — muestra unknown como un signo de interrogación, no con una omisión silenciosa.
processing_level sale del grupo NOVA registrado del producto; solo cuando no hay ninguno se estima a partir de los ingredientes (processing_basis: "model").
disclaimer va en todas las respuestas. Muéstralo — el análisis es informativo, no un consejo médico.

Los análisis se guardan en caché por producto e idioma, así que el primero que llama paga la latencia de generación y todos los demás obtienen una respuesta instantánea — al mismo precio de 4 créditos. cached: true te dice en qué caso estás.

Puedes ver este endpoint en acción en cualquier página de producto — el panel «Análisis con IA» es exactamente esta respuesta.

Analizar tus propios datos de producto

¿Y los productos que no están en el catálogo — marcas blancas, lanzamientos nuevos, SKU internos? POST /v1/analyze/custom (también 4 créditos) acepta los datos del producto en el cuerpo de la petición y ejecuta el mismo análisis:

curl -X POST "https://foodbase.dev/v1/analyze/custom" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Protein bar cocoa",
    "brand": "MyBrand",
    "ingredients": "Oats, whey protein, cocoa, honey",
    "nutrients": { "energy_kcal": 380, "proteins_g": 30, "sugars_g": 18 }
  }'

Dos reglas mantienen la salida honesta:

Un nombre solo se rechaza (422). Debes proporcionar ingredientes y/o al menos un valor nutricional por 100 g — de lo contrario, el modelo no tendría nada factual que analizar.
Los valores inverosímiles se rechazan, no se corrigen en silencio. Los campos de nutrientes tienen límites por 100 g (energía ≤ 900 kcal, gramos ≤ 100, sodio ≤ 10000 mg), y las claves de nutrientes desconocidas son un error en lugar de ignorarse.

El objeto nutrients admite los macronutrientes estándar más un conjunto seleccionado de vitaminas y minerales (vitamina C, D, B12, folato, E, calcio, hierro, potasio, magnesio, zinc) — dale más y los puntos positivos serán más precisos: si aportas valores de calcio y hierro obtendrás cosas como «Source of calcium (150 mg per 100 g)» siempre que un valor alcance el umbral de la UE (15 % de la ingesta de referencia por 100 g; el doble para «alto en»).

La respuesta replica la del análisis del catálogo, con un input_hash en lugar de un food_id — entradas idénticas producen el mismo hash, así que repetir el análisis de los mismos datos acierta en caché. También hay un campo opcional barcode: no se analiza, sirve para marcar el producto como uno que te gustaría ver añadido al catálogo.

¿Prefieres un formulario a un cuerpo JSON? El playground tiene este mismo endpoint como formulario para rellenar.

Notas prácticas de integración

Idioma: pasa lang (en, fr, es, de, it, bg) y todo el análisis — resumen, puntos positivos, advertencias, alérgenos — vuelve en ese idioma. Los veredictos son idénticos en todos los idiomas por construcción. Cada idioma tiene su propia caché.
Créditos: 4 créditos por llamada, incluidos los aciertos de caché. Los fallos (petición incorrecta, error del proveedor, producto desconocido) se reembolsan automáticamente — solo pagas por las respuestas.
Idempotencia: no existe — un doble envío son dos cobros. Desactiva tu botón mientras hay una petición en curso.
Presentación: la respuesta está pensada para encajar directamente en la interfaz — párrafo de resumen, lista de puntos positivos, lista de advertencias, una línea de alérgenos, cuatro insignias de dieta con su base, una etiqueta de nivel de procesamiento. Así es exactamente como la muestran las páginas de producto de aquí.
¿Texto de etiqueta roto? Si la lista de ingredientes del propio producto está distorsionada (espacios que faltan, caracteres rotos, TODO EN MAYÚSCULAS), POST /v1/correct/product la repara para todos y el análisis se regenera a partir del texto corregido.

Pruébalo

Consigue una clave de API gratuita (20 créditos de IA incluidos), abre la documentación o prueba los paneles en vivo en cualquier página de producto.