API di analisi alimentare IA

Indica il prodotto, scegli la lingua

POST /v1/analyze/product accetta un corpo JSON con esattamente uno tra food_id o barcode (da 8 a 14 cifre; le varianti GTIN con zeri di riempimento si risolvono) più una lang facoltativa. Se invii entrambi o nessuno ottieni un 422 che dice “Provide exactly one of food_id or barcode”, con il credito rimborsato. Le stringhe vuote contano come omesse.

lang è en per impostazione predefinita e accetta anche fr, es, de, it e bg. Imposta la lingua del testo, non i verdetti: ogni verdetto è calcolato dal record con regole fisse ed espresso con un dizionario di frasi in ciascuna lingua, e i giudizi del modello vengono formulati una volta per prodotto e condivisi da tutte le lingue, quindi un prodotto non può essere vegano in inglese e non esserlo in tedesco. Le regole leggono i nutrienti, le etichette, i tag di allergeni e tracce e il gruppo NOVA del record, gli stessi dati che restituiscono la Food Database API e la Nutrition API. Partendo da una foto, la Food Image Recognition API ti dà prima il food_id.

Leggere l'analisi, campo per campo

L'esempio è la risposta reale per la Nutella (codice a barre 3017620422003, lang en). highlights sono solo punti di forza: un prodotto ne ottiene uno quando soddisfa la condizione di un claim nutrizionale del Regolamento UE 1924/2006, come basso contenuto di sale (al massimo 0,3 g per 100 g), fonte di proteine (almeno il 12% dell'energia) o alto contenuto di fibre (almeno 6 g). warnings sono solo avvertenze: un nutriente sopra la soglia “high” del fronte confezione UK FSA (zuccheri sopra 22,5 g per 100 g, o sopra 11,25 g per 100 ml per le bevande), una porzione grande che supera il limite per porzione della FSA, oppure caffeina, dolcificanti, alcol o olio di palma negli ingredienti. Un argomento non è mai in entrambi, e ogni numero è il valore del record stesso.

nutrient_levels fornisce gli stessi verdetti come dati: grassi, grassi saturi, zuccheri e sale, ciascuno low, medium o high, con basis per_100 o per_portion. Una cola da 330 ml con 10,6 g di zuccheri per 100 ml è medium per 100 ml ma high per lattina, quindi la sua avvertenza dice “High in sugars (35 g per serving)”. allergens elenca gli allergeni UE-14 dichiarati come contains e may_contain, con status “not_stated” quando il record non ha dati sugli allergeni, il che significa controlla la confezione, non “nessuno”.

diets_detail risponde su vegan, vegetarian, gluten_free e lactose_free con un value e una basis. Decide per primo un claim in etichetta (vegan, senza glutine, senza lattosio, loghi di certificazione); poi un allergene dichiarato o un tag di carne esclude una dieta; altrimenti la risposta viene dall'elenco degli ingredienti. Senza glutine e senza lattosio sono “yes” solo con un claim in etichetta: un elenco di ingredienti senza fonti di glutine dà “no_known_source”, perché un prodotto non certificato può comunque essere contaminato. diets mantiene la vecchia forma yes/no/unknown, con no_known_source riportato come unknown.

processing_level è il gruppo NOVA come etichetta — unprocessed (1), culinary_ingredient (2: oli, burro, zucchero), processed (3), ultra_processed (4) — dal gruppo NOVA del record (processing_basis “nova”); solo quando il record non ne ha uno viene stimato dagli ingredienti (“model”). per_serving è calcolato dalla dimensione della porzione del record, oppure è null quando non ce n'è una registrata. disclaimer è una stringa fissa; mostralo, perché il testo è generato e descrive il record del catalogo, non la confezione che l'utente ha in mano.

Crediti, cache e rimborsi

Ogni chiamata costa 4 crediti IA da una quota mensile condivisa da tutte le chiavi dell'account (20 Free, 500 Starter, 1.300 Pro, 3.000 Enterprise; reset il primo del mese UTC), poi dai crediti di ricarica una tantum quando la quota non può più coprire una chiamata. Vengono scalati prima dell'inferenza, e ogni risposta porta X-Credits-Limit, X-Credits-Remaining (mensili più ricarica), X-Credits-Topup-Remaining e X-Credits-Reset.

Le analisi sono messe in cache per prodotto, lingua e versione dell'analisi, legate all'updated_at del record, quindi un prodotto reimportato o corretto viene analizzato di nuovo. Il source_updated_at della risposta indica la versione dei dati da cui è stata creata; l'updated_at del record alimentare ti dice se è ancora attuale. Un riscontro in cache restituisce cached: true e viene comunque addebitato di 4 crediti: sugli endpoint analyze non ci sono rimborsi per i riscontri in cache. Metti in cache la risposta da solo, con chiave food_id e lang, se mostri spesso lo stesso prodotto.

I rimborsi avvengono solo quando non è stato prodotto nulla: 404, 422, 502 (il messaggio termina con “You were not charged.”) e 503. Un 401 o un 429 non toccano mai i crediti.

I tuoi dati di prodotto: /analyze/custom

POST /v1/analyze/custom restituisce lo stesso oggetto di analisi per un prodotto che descrivi tu: un articolo a marchio del distributore, un nuovo lancio, un'etichetta appena estratta. Il corpo contiene name (da 2 a 150 caratteri) più facoltativi brand, category, quantity, ingredients (fino a 3.000 caratteri), un oggetto nutrients con valori per 100 g e lang. Non ci sono campi di domanda o profilo a testo libero, né claim in etichetta o tag di allergeni, quindi le diete vengono dagli ingredienti e senza glutine o senza lattosio è al massimo no_known_source.

Un name da solo è un 422: invia ingredients, almeno un valore nutrizionale, o entrambi, perché il modello non può inventare dati nutrizionali. nutrients è rigido, con diciannove chiavi chiamate come le colonne del catalogo (energy_kcal, sugars_g, sodium_mg, calcium_mg e così via); una chiave sconosciuta è un 422, e i valori fuori intervallo vengono rifiutati e non troncati.

La risposta ha input_hash al posto di food_id, uno SHA-256 dell'input canonicalizzato, quindi dati e lang identici sono un riscontro in cache, addebitato come ogni altro. Un barcode facoltativo non viene analizzato; serve solo a segnalare il prodotto come uno che vuoi nel catalogo.

Aggiungere una lingua: /translate/product

POST /v1/translate/product accetta food_id o barcode e una lang obbligatoria, traduce il nome e il testo degli ingredienti del prodotto e scrive il risultato nel catalogo come sovrapposizione che sopravvive alle reimportazioni ed è visibile a ogni chiamante come nuova voce {lang, text} negli array name e ingredients del record, e tramite name_localized nella ricerca. I dati d'etichetta già presenti in quella lingua non vengono mai sovrascritti.

cached: true qui significa che la lingua esisteva già e i tuoi 4 crediti vengono rimborsati. force: true rigenera una traduzione che ritieni scadente, ma solo un testo di una precedente esecuzione IA; se il testo della lingua proviene dall'etichetta o da una correzione manuale, ottieni un 422 con i crediti rimborsati. Un output a bassa confidence o non sicuro non viene mai memorizzato: la chiamata restituisce 502 e non ti viene addebitato nulla.

Correggere il testo d'etichetta rotto: /correct/product

Il testo d'etichetta nella lingua del prodotto è a volte rotto alla fonte: errori OCR, spazi mancanti dopo le virgole, elenchi tutti in maiuscolo, caratteri corrotti come “crème” al posto di “crème”, o un passaggio ripetuto due volte. POST /v1/correct/product lo ripara per tutti, per 4 crediti. La riparazione può cambiare solo la forma: il codice verifica che nessun ingrediente, numero, percentuale o numero E sia stato aggiunto o rimosso, che virgole e parentesi siano rimaste dove erano e che ogni allergene e la sua enfasi siano sopravvissuti. Una riparazione che non supera i controlli non viene memorizzata né addebitata.

Quando è il contenuto stesso a essere sbagliato, POST /v1/correct/product/photo accetta la foto dell'etichetta e usa come prova l'elenco degli ingredienti letto da essa, per 4 crediti. Leggere la foto è la parte costosa, quindi una foto letta ma non utilizzabile (nessun elenco di ingredienti visibile, codice a barre non leggibile per intero, un prodotto diverso o una lettura troppo incerta per fidarsene) risponde 422 ed è addebitata come /vision/label. Ogni correzione conserva il testo precedente per il ripristino, si riapplica dopo le reimportazioni solo finché la fonte originale distribuisce ancora il testo che è stato corretto, e fa rigenerare alla richiesta successiva le traduzioni IA del vecchio testo. Anche l'analisi del prodotto si rigenera, perché il record è cambiato.