API за AI анализ на храни

Адресирай продукта, избери езика

POST /v1/analyze/product приема JSON тяло с точно едно от food_id или barcode (8 до 14 цифри; GTIN варианти с водещи нули се разрешават) плюс незадължителен lang. Изпрати и двете или нито едно и получаваш 422 с текст „Provide exactly one of food_id or barcode“, а кредитът се възстановява. Празните низове се броят за пропуснати.

lang е en по подразбиране и приема още fr, es, de, it и bg. Той задава езика на текста, не присъдите: всяка присъда се изчислява от записа по фиксирани правила и се формулира от речник с фрази на всеки език, а преценките на модела се правят веднъж за продукт и се споделят от всички езици, така че продукт не може да е веган на английски и да не е на немски. Правилата четат хранителните вещества, етикетите, таговете за алергени и следи и NOVA групата на записа — същите данни, които връщат API за база данни с храни и API за хранителни стойности. От снимка API за разпознаване на храни от снимка първо ти дава food_id.

Четене на анализа, поле по поле

Примерът е живият отговор за Nutella (баркод 3017620422003, lang en). highlights са само добри страни: продуктът печели такава, когато отговаря на условието на хранителна претенция по Регламент (ЕО) 1924/2006 на ЕС, като ниско съдържание на сол (най-много 0,3 g на 100 g), източник на протеин (поне 12% от енергията) или високо съдържание на фибри (поне 6 g). warnings са само предупреждения: хранително вещество над прага „high“ за предната страна на опаковката по UK FSA (захари над 22,5 g на 100 g или над 11,25 g на 100 ml за напитки), голяма порция, която преминава границата на FSA на порция, или кофеин, подсладители, алкохол или палмово масло в съставките. Една тема никога не е и двете, а всяко число е собствената стойност на записа.

nutrient_levels дава същите присъди като данни: мазнини, наситени мазнини, захари и сол, всяка low, medium или high, с basis per_100 или per_portion. Кола от 330 ml с 10,6 g захари на 100 ml е medium на 100 ml, но high на кутия, затова предупреждението ѝ гласи „High in sugars (35 g per serving)“. allergens изброява декларираните алергени от EU-14 като contains и may_contain, със status „not_stated“, когато записът няма данни за алергени, което означава „провери опаковката“, а не „няма“.

diets_detail отговаря за vegan, vegetarian, gluten_free и lactose_free със value и basis. Първо решава претенция на етикета (веган, без глутен, без лактоза, сертификационни лога); после деклариран алерген или таг за месо изключва диета; иначе отговорът идва от списъка със съставки. Без глутен и без лактоза са „yes“ само с претенция на етикета: списък със съставки без източник на глутен дава „no_known_source“, защото несертифициран продукт все пак може да е замърсен. diets пази по-старата форма yes/no/unknown, като no_known_source се отчита като unknown.

processing_level е NOVA групата като етикет — unprocessed (1), culinary_ingredient (2: масла, масло, захар), processed (3), ultra_processed (4) — от NOVA групата на записа (processing_basis „nova“); само когато записът няма такава, се преценява по съставките („model“). per_serving се изчислява от размера на порцията в записа или е null, когато няма такъв. disclaimer е фиксиран низ; показвай го, защото текстът е генериран и описва записа в каталога, а не опаковката в ръцете на потребителя.

Кредити, кеширане и възстановявания

Всяко извикване струва 4 AI кредита от месечен лимит, споделен между всички ключове на акаунта (20 Free, 500 Starter, 1 300 Pro, 3 000 Enterprise; нулира се на първо число от месеца по UTC), а после от еднократни кредити за презареждане, когато лимитът не може да покрие извикване. Удържа се преди извода и всеки отговор носи X-Credits-Limit, X-Credits-Remaining (месечни плюс презареждане), X-Credits-Topup-Remaining и X-Credits-Reset.

Анализите се кешират по продукт, език и версия на анализа, свързани с updated_at на записа, така че повторно внесен или поправен продукт се анализира наново. source_updated_at в отговора назовава версията на данните, от която е направен; updated_at на записа за храната ти казва дали още е актуален. Попадение връща cached: true и пак се таксува с 4 кредита: няма възстановявания за попадения в кеша при крайните точки за анализ. Кеширай отговора сам, с ключ food_id и lang, ако показваш често един и същ продукт.

Възстановявания има само когато нищо не е произведено: 404, 422, 502 (съобщението завършва с „You were not charged.“) и 503. 401 или 429 никога не засягат кредитите.

Собствените ти данни за продукт: /analyze/custom

POST /v1/analyze/custom връща същия обект analysis за продукт, който описваш сам: артикул с търговска марка на веригата, нов продукт, етикет, който току-що си извлякъл. Тялото носи name (2 до 150 символа) плюс незадължителни brand, category, quantity, ingredients (до 3000 символа), обект nutrients със стойности на 100 g и lang. Няма полета за свободен въпрос или профил, нито претенции на етикета или тагове за алергени, така че диетите идват от съставките, а без глутен или без лактоза е най-много no_known_source.

Само name е 422: изпрати ingredients, поне една стойност за хранително вещество или и двете, защото моделът не може да измисля хранителни факти. nutrients е стриктен, с деветнайсет ключа, наименувани като колоните на каталога (energy_kcal, sugars_g, sodium_mg, calcium_mg и така нататък); непознат ключ е 422, а стойности извън обхвата се отхвърлят, а не се орязват.

Отговорът има input_hash вместо food_id — SHA-256 на каноничния вход, така че идентични данни и lang са попадение в кеша, таксувано като всяко друго. Незадължителният barcode не се анализира; той само отбелязва продукта като такъв, който искаш в каталога.

Добавяне на език: /translate/product

POST /v1/translate/product приема food_id или barcode и задължителен lang, превежда името и текста на съставките на продукта и записва резултата в каталога като наслагване, което оцелява при повторен внос и е видимо за всеки, който вика, като ново вписване {lang, text} в масивите name и ingredients на записа и чрез name_localized в търсенето. Данни от етикета на този език никога не се презаписват.

cached: true тук означава, че езикът вече е съществувал и 4-те ти кредита се възстановяват. force: true прегенерира превод, който смяташ за лош, но само текст от по-ранно AI изпълнение; ако текстът на езика е от етикета или ръчна поправка, получаваш 422 с възстановени кредити. Нискоуверен или небезопасен изход никога не се записва: извикването връща 502 и не си таксуван.

Поправяне на счупен текст от етикет: /correct/product

Текстът на етикета на собствения език на продукта понякога е счупен в източника: OCR грешки, липсващи интервали след запетаи, списъци с ГЛАВНИ БУКВИ, счупени символи като „crème“ вместо „crème“ или пасаж, повторен два пъти. POST /v1/correct/product го поправя за всички, за 4 кредита. Поправката може да променя само формата: кодът проверява, че нито една съставка, число, процент или E-номер не е добавена или премахната, че запетаите и скобите са останали на местата си и че всеки алерген и подчертаването му са оцелели. Поправка, която не мине проверката, не се записва и не се таксува.

Когато съдържанието е грешно, POST /v1/correct/product/photo приема снимка на етикета и използва прочетения от нея списък със съставки като доказателство, за 4 кредита. Четенето на снимката е скъпата част, така че снимка, която е прочетена, но не може да се използва (не се вижда списък със съставки, баркодът не се чете изцяло, друг продукт или четене, твърде несигурно за доверие), отговаря 422 и се таксува като /vision/label. Всяка поправка пази предишния текст за връщане, прилага се наново след повторен внос само докато изходният източник още доставя текста, който е бил поправен, и кара AI преводите на стария текст да се прегенерират при следващата им заявка. Анализът на продукта също се прегенерира, защото записът се е променил.