API за разпознаване на храни от снимка

Коя крайна точка за коя снимка

И четирите операции приемат едно multipart/form-data поле с име image. Сървърът проверява байтовете, не името на файла: JPEG, PNG или WebP, до 8 MB, иначе качването се отхвърля, преди да тръгне какъвто и да е модел. Снимките се завъртат автоматично по EXIF и се оразмеряват до 1024 px по най-дългата страна, така че снимка в пълна резолюция струва само време за качване.

POST /v1/vision/barcode декодира EAN-13, EAN-8, UPC-A, UPC-E и Code-128 с обикновено компютърно зрение и търси кода точно като GET /foods/barcode/{code}. Тялото на 200 е { barcode, product } с пълния запис от каталога (id, name_default, brand, nutrition_summary и останалото). Не се изпълнява езиков модел, затова струва 0 кредита и се отчита като извикване на данни.

Другите три са AI извиквания. /vision/product чете предната страна на опаковката в extracted { name, brand, quantity, lang, confidence } плюс подредени matches. /vision/label преписва панела с хранителни стойности в числа на 100 g, ingredients_text, allergens и serving; панел, който отпечатва само стойности на порция, се преобразува на 100 g в код, когато размерът на порцията е отпечатан (basis per_100g, converted: true); когато не е, полетата на 100 са null, а отпечатаните числа се връщат под per_serving (basis per_serving). /vision/meal връща items[] от разпознати ястия с оценки на порцията. Всеки отговор носи request_id и cached.

• Заявка без полето image е 422 Validation Error с details[].field = "image".

Четене на отговор от /vision/product

extracted.lang е езикът, прочетен от опаковката (bg за етикет на кирилица), и управлява езиково-съобразеното търсене в каталога. confidence е от 0 до 1 и ограничава това търсене: каталогът се заявява само когато confidence е поне 0,3 и е прочетено име; иначе matches е празен.

matches съдържа до 5 продукта, най-добрият първи, всеки { score, product } в същата пълна форма FoodItem като запис от API за база данни с храни. score произлиза от confidence и ранга, така че най-горното съвпадение носи самото confidence, а всяко следващо има по-ниска оценка. Запази matches[0].product.id; id-тата са стабилни при повторен внос.

Пропуск изглежда като този отговор на малка снимка на продукт: {"matches":[],"extracted":{"lang":"","name":"","brand":"","quantity":"","confidence":0},"request_id":"bcca8231-f335-4468-81bf-e587b614d9a4","cached":true}. Празните низове и confidence 0 означават, че не е могло да се прочете име; cached: true означава, че същите байтове са били виждани преди, а извикването пак е таксувано с 3 кредита.

Етикети и ястия: прочетено срещу оценено

/vision/label е преписване, не извод. energy_kcal, fat_g, saturated_fat_g, carbs_g, sugars_g, fiber_g, proteins_g и salt_g се четат както са отпечатани, а всичко, което не е на етикета, се връща null, никога налучквано. Четим баркод на същата снимка се връща като extracted.barcode и се търси: съвпадение попълва product с пълния FoodItem, иначе product е null.

/vision/meal е обратното и полето му disclaimer го казва. Всеки елемент има dish, kind, portion_g_est и confidence, плюс match, когато ястието е разрешено до генерична храна от USDA: id, name_default, per_100g { energy_kcal, proteins_g, carbs_g, fat_g } и estimated_kcal, което е per_100g.energy_kcal по portion_g_est, делено на 100. Елементите са или цели ястия (kind „dish“: бургер, лазаня), или отделните компоненти на чинията (kind „component“: ориз, пилешко на скара, салата), никога ястие заедно със собствените му части, така че estimated_total_kcal, сборът от елементите, които имат такова, не брои нищо два пъти; то е null, когато никой елемент няма. Съпоставянето използва английски генерични храни — USDA FNDDS за ястия, както се ядат (лазаня, бурито, pad thai), после USDA SR Legacy за съставки — така че match.name_default е на английски независимо от снимката, а елемент без уверено съвпадение получава match: null вместо грешна храна.

• Показвай текста на disclaimer на крайните потребители на оценките за хранения; ястие с match: null пак струва 5-те кредита.

Кредити, възстановявания и лимитът за vision

Кредитите се удържат преди извода: 3 за product, 4 за label, 5 за meal. Месечният лимит е споделен между всички ключове на акаунта (Free 20, Starter 500, Pro 1 300, Enterprise 3 000) и се нулира на първо число от месеца по UTC. Когато не може да покрие извикване, го плащат кредити от еднократни пакети за презареждане (купени от страницата Billing на таблото, валидни 12 месеца). AI отговорите носят X-Credits-Limit, X-Credits-Remaining (месечни плюс презареждане), X-Credits-Topup-Remaining и X-Credits-Reset; GET /v1/credits връща двата баланса безплатно.

Изчерпването е 402, не 429: { "error": "Insufficient credits", "message": "This call costs 3 credits and your free plan's monthly allowance of 20 is exhausted, with no top-up credits left. Buy more at https://foodbase.dev/dashboard/billing (they apply instantly), or wait for the reset on 2026-12-01.", "top_up_url": "https://foodbase.dev/dashboard/billing" }. Възстановявания има само когато заявката изобщо не е стигнала до отговор: отхвърлено изображение (413 или 422), липсващо поле (422), грешка на доставчика (502, съобщението завършва с „You were not charged.“) или изключен vision (503). Попаденията в кеша се таксуват с пълна цена нарочно.

AI извикванията имат собствен лимит за секунда, без burst: 1/с във Free и Starter, 2/с в Pro, 5/с в Enterprise на ключ и три пъти повече за целия акаунт. Отговорите носят X-RateLimit-Vision-Limit и X-RateLimit-Vision-Remaining; надвишаването е 429 с Retry-After: 1 и без таксуване, защото лимитерът се изпълнява преди удръжката.

Потокът със сканиране и снимката

Първо най-евтиното. Декодирай баркода на устройството и извикай API за търсене по баркод, или остави /vision/barcode да го декодира за 0 кредита. Само когато няма баркод или търсенето върне 404, изпрати предната страна на опаковката към /vision/product. С matches[0].product.id вземи разбивката на 100 g от API за хранителни стойности или оценка с прости думи от API за AI анализ на храни.

Качеството на снимката определя confidence. За /vision/product кадрирай предната страна на опаковката с четливи име, марка и размер на опаковката и нищо друго в кадъра. За /vision/label положи панела плосък, запълни кадъра с таблицата с хранителни стойности и абзаца със съставки и включи баркода, ако се събира. За /vision/barcode правилото е собственото 422 съобщение на сървъра: запълни кадъра с баркода, избягвай отблясъци, дръж го на фокус.

• Повтори 502 след кратка пауза; кредитите ти са възстановени. Не повтаряй 200 с ниско confidence; снимай отново.