AI анализ на продукти: резюмета, които потребителите ти наистина разбират

Проблемът със суровите хранителни данни

Отговорът от API-то ти казва sugars_g: 56.3. Потребителят ти иска да знае: много ли е това? Преодоляването на тази пропаст — превръщането на числа и списъци със съставки в нещо, спрямо което човек може да действа — обикновено е мястото, където приложенията за хранене или инвестират сериозно, или се отказват.

Ендпойнтите за анализ правят тази стъпка вместо теб: едно извикване връща кратък, фактически и разбираем анализ, генериран единствено от данните за продукта. Преценките — кое е високо, кое е плюс, кои алергени, кои хранителни режими — идват от фиксирани, публикувани прагове, приложени в кода; AI пише резюмето от две изречения и чете списъка със съставки там, където е нужна преценка. Без измислени числа, без здравни твърдения и „неизвестно“ вместо предположение.

Анализ на продукт от каталога

POST /v1/analyze/product приема food_id или barcode (едно от двете), струва 4 кредита и отговаря на всеки от 6-те езика:

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…"
}

(Съкратено: отговорът съдържа още nutrient_levels, пълното diets_detail, nova_group и flags.) Няколко неща, които е добре да знаеш за структурата:

highlights са само плюсове, warnings са само предупреждения — и една тема никога не се появява и в двете. Плюс означава, че продуктът отговаря на условието за хранителна претенция по правилата на ЕС (ниско съдържание на сол е най-много 0,3 г на 100 г; източник на белтъчини е поне 12% от енергията). Предупреждение е „високо“ ниво по UK FSA, голяма порция, която надхвърля лимита на FSA за порция, или кофеин, подсладители, алкохол или палмово масло в съставките.
allergens са изброени отделно: 14-те алергена по ЕС, които етикетът декларира, разделени на „съдържа“ и „може да съдържа“, с изречение на съответния език. status: "not_stated" означава, че записът няма данни за алергени — провери опаковката.
diets_detail казва откъде идва всеки отговор: от твърдение на етикета, от деклариран алерген или от списъка със съставки. Без глутен и без лактоза са yes само при твърдение на етикета; списък без съставки с глутен дава no_known_source, защото несертифициран продукт пак може да е замърсен. diets запазва простия изглед yes / no / unknown — показвай unknown като въпросителен знак, а не като тихо пропускане.
processing_level идва от записаната NOVA група на продукта; само когато няма такава, степента се преценява от съставките (processing_basis: "model").
disclaimer идва с всеки отговор. Показвай го — анализът е информативен, а не медицински съвет.

Анализите се кешират по продукт и език, така че първият, който извика, изчаква генерирането, а всички след него получават мигновен отговор — на същата цена от 4 кредита. cached: true ти казва кой е случаят.

Можеш да видиш този ендпойнт визуализиран на всяка продуктова страница — панелът „AI анализ“ е точно този отговор.

Анализ на собствени данни за продукти

А какво става с продуктите, които ги няма в каталога — собствени марки, нови продукти, вътрешни SKU-та? POST /v1/analyze/custom (също 4 кредита) приема данните за продукта в тялото на заявката и прави същия анализ:

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 }
  }'

Две правила пазят резултата честен:

Само име се отхвърля (422). Трябва да подадеш съставки и/или поне една хранителна стойност на 100 г — иначе моделът няма да има нищо фактическо за анализ.
Неправдоподобните стойности се отхвърлят, а не се поправят тихомълком. Полетата за хранителни вещества имат горни граници на 100 г (енергия ≤ 900 kcal, грамове ≤ 100, натрий ≤ 10000 mg), а непознатите ключове за хранителни вещества водят до грешка, вместо да бъдат игнорирани.

Обектът nutrients приема стандартните макроси плюс подбран набор от витамини и минерали (витамин C, D, B12, фолат, E, калций, желязо, калий, магнезий, цинк) — колкото повече подадеш, толкова по-точни стават плюсовете: подай стойности за калций и желязо и ще получиш неща като „Източник на калций (150 mg на 100 г)“ винаги когато стойността достигне прага на ЕС (15% от референтния прием на 100 г; двойно повече за „с високо съдържание на“).

Отговорът повтаря анализа от каталога, с input_hash вместо food_id — еднакви входни данни дават еднакъв хеш, така че повторните анализи на същите данни са попадения в кеша. Има и незадължително поле barcode: то не се анализира, а маркира продукта като такъв, който би искал да видиш добавен в каталога.

Предпочиташ форма пред JSON тяло? В playground-а точно този ендпойнт е наличен като форма за попълване.

Практически бележки за интеграцията

Език: подай lang (en, fr, es, de, it, bg) и целият анализ — резюме, плюсове, предупреждения, алергени — се връща на този език. Преценките са еднакви на всеки език по конструкция. Всеки език се кешира отделно.
Кредити: 4 кредита на извикване, включително при попадения в кеша. Неуспешните заявки (грешна заявка, грешка на доставчика, непознат продукт) се възстановяват автоматично — плащаш само за отговори.
Идемпотентност: няма — двойното изпращане е две таксувания. Деактивирай бутона си, докато заявката е в процес.
Визуализиране: отговорът е проектиран да се пренася директно в интерфейса — абзац с резюмето, списък с плюсове, списък с предупреждения, ред за алергените, четири значки за хранителни режими с основанието им, етикет за степента на преработка. Точно така го показват и продуктовите страници тук.
Повреден текст на етикета? Ако собственият списък със съставки на продукта е объркан (липсващи интервали, счупени символи, САМО ГЛАВНИ БУКВИ), POST /v1/correct/product го поправя за всички и анализът се генерира наново от поправения текст.

Пробвай

Вземи си безплатен API ключ (20 AI кредита включени), отвори документацията или разгледай живите панели на която и да е продуктова страница.