API di riconoscimento di immagini di cibo

Quale endpoint per quale foto

Tutte e quattro le operazioni accettano un solo campo multipart/form-data chiamato image. Il server legge i byte, non il nome del file: JPEG, PNG o WebP, fino a 8 MB, altrimenti il caricamento viene rifiutato prima che giri qualsiasi modello. Le foto vengono ruotate automaticamente dall'EXIF e ridimensionate a 1024 px sul lato più lungo, quindi uno scatto a piena risoluzione costa solo tempo di caricamento.

POST /v1/vision/barcode decodifica EAN-13, EAN-8, UPC-A, UPC-E e Code-128 con semplice computer vision e cerca il codice esattamente come GET /foods/barcode/{code}. Il corpo 200 è { barcode, product } con il record completo del catalogo (id, name_default, brand, nutrition_summary e il resto). Non gira alcun modello linguistico, quindi costa 0 crediti ed è conteggiata come una chiamata ai dati.

Le altre tre sono chiamate IA. /vision/product legge il fronte di una confezione in extracted { name, brand, quantity, lang, confidence } più matches ordinate. /vision/label trascrive una tabella nutrizionale in numeri per 100 g, ingredients_text, allergens e serving; una tabella che stampa solo valori per porzione viene convertita a per 100 g nel codice quando la dimensione della porzione è stampata (basis per_100g, converted: true); quando non lo è, i campi per 100 sono null e i numeri stampati tornano sotto per_serving (basis per_serving). /vision/meal restituisce items[] di piatti riconosciuti con stime di porzione. Ogni risposta porta request_id e cached.

• Una richiesta senza il campo image è un 422 Validation Error con details[].field = "image".

Leggere una risposta di /vision/product

extracted.lang è la lingua letta sulla confezione (bg per un'etichetta in cirillico) e guida una ricerca nel catalogo attenta alla lingua. confidence va da 0 a 1 e condiziona quella ricerca: il catalogo viene interrogato solo quando confidence è almeno 0,3 e un nome è stato letto; altrimenti matches è vuoto.

matches contiene fino a 5 prodotti, dal migliore, ciascuno { score, product } nella stessa forma completa FoodItem di un record della Food Database API. score deriva da confidence e dalla posizione, quindi la prima corrispondenza porta la confidence stessa e ogni voce successiva ha un punteggio più basso. Conserva matches[0].product.id; gli id sono stabili tra le reimportazioni.

Un mancato riscontro si presenta così, per la foto di un piccolo prodotto: {"matches":[],"extracted":{"lang":"","name":"","brand":"","quantity":"","confidence":0},"request_id":"bcca8231-f335-4468-81bf-e587b614d9a4","cached":true}. Stringhe vuote e confidence 0 significano che non è stato possibile leggere alcun nome; cached: true significa che gli stessi byte erano già stati visti, e la chiamata è stata comunque addebitata di 3 crediti.

Etichette e pasti: letto contro stimato

/vision/label è trascrizione, non inferenza. energy_kcal, fat_g, saturated_fat_g, carbs_g, sugars_g, fiber_g, proteins_g e salt_g sono letti come stampati, e qualsiasi cosa non presente in etichetta torna null, mai ipotizzata. Un codice a barre leggibile nella stessa foto viene restituito come extracted.barcode e cercato: se c'è una corrispondenza, product si riempie con il FoodItem completo, altrimenti product è null.

/vision/meal è l'opposto, e il suo campo disclaimer lo dice. Ogni elemento ha dish, kind, portion_g_est e confidence, più match quando il piatto è stato risolto in un alimento generico USDA: id, name_default, per_100g { energy_kcal, proteins_g, carbs_g, fat_g } e estimated_kcal, che è per_100g.energy_kcal moltiplicato per portion_g_est diviso 100. Gli elementi sono o piatti interi (kind "dish": un hamburger, una lasagna) o i componenti separati di un vassoio (kind "component": riso, pollo alla griglia, insalata), mai un piatto insieme alle sue parti, quindi estimated_total_kcal, la somma degli elementi che ne hanno uno, non conta nulla due volte; è null quando nessun elemento ne ha uno. La corrispondenza usa alimenti generici in inglese — USDA FNDDS per i piatti come si mangiano (lasagna, burritos, pad thai), poi USDA SR Legacy per gli ingredienti — quindi match.name_default è in inglese qualunque sia la foto, e un elemento senza una corrispondenza sicura riceve match: null invece di un alimento sbagliato.

• Mostra il testo del disclaimer agli utenti finali delle stime dei pasti; un piatto con match: null costa comunque i 5 crediti.

Crediti, rimborsi e limite di frequenza della visione

I crediti vengono scalati prima dell'inferenza: 3 per product, 4 per label, 5 per meal. La quota mensile è condivisa da tutte le chiavi dell'account (Free 20, Starter 500, Pro 1.300, Enterprise 3.000) e si azzera il primo del mese UTC. Quando non può più coprire una chiamata, la pagano i crediti dei pacchetti di ricarica una tantum (acquistabili nella pagina Fatturazione della dashboard, validi 12 mesi). Le risposte IA portano X-Credits-Limit, X-Credits-Remaining (mensili più ricarica), X-Credits-Topup-Remaining e X-Credits-Reset; GET /v1/credits restituisce gratis entrambi i saldi.

Restare senza crediti è un 402, non un 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" }. I rimborsi avvengono solo quando la richiesta non è mai arrivata a una risposta: immagine rifiutata (413 o 422), campo mancante (422), guasto del provider (502, il messaggio termina con “You were not charged.”) o visione disattivata (503). Le risposte dalla cache sono addebitate a prezzo pieno di proposito.

Le chiamate IA hanno un proprio limite al secondo, senza burst: 1/s su Free e Starter, 2/s su Pro, 5/s su Enterprise per chiave, e tre volte tanto sull'intero account. Le risposte portano X-RateLimit-Vision-Limit e X-RateLimit-Vision-Remaining; superarlo è un 429 con Retry-After: 1 e nessun addebito, perché il limitatore agisce prima della detrazione.

Il flusso di scansione e la foto

Prima il meno costoso. Decodifica il codice a barre sul dispositivo e chiama la Barcode Lookup API, oppure lascia che sia /vision/barcode a decodificarlo per 0 crediti. Solo quando non c'è un codice a barre, o la ricerca restituisce 404, invia il fronte della confezione a /vision/product. Con matches[0].product.id, recupera il dettaglio per 100 g dalla Nutrition API oppure un giudizio in linguaggio semplice dalla AI Food Analysis API.

La qualità della foto decide la confidence. Per /vision/product inquadra il fronte della confezione con nome, marca e formato leggibili e nient'altro nell'inquadratura. Per /vision/label appoggia la tabella in piano, riempi l'inquadratura con la tabella nutrizionale e il paragrafo degli ingredienti, e includi il codice a barre se ci sta. Per /vision/barcode vale il messaggio 422 del server stesso: riempi l'inquadratura con il codice a barre, evita i riflessi, mantienilo a fuoco.

• Riprova un 502 dopo una breve attesa; sei stato rimborsato. Non riprovare un 200 a bassa confidence; scatta di nuovo.