Analisi dei prodotti con l'IA: riassunti che i tuoi utenti leggono davvero

Il problema dei dati nutrizionali grezzi

La risposta della tua API dice sugars_g: 56.3. Il tuo utente vuole sapere: è tanto? Colmare questo divario — trasformare numeri e liste di ingredienti in qualcosa su cui una persona possa agire — è di solito il punto in cui le app di nutrizione investono moltissimo oppure lasciano perdere.

Gli endpoint di analisi fanno questo passaggio al posto tuo: una sola chiamata restituisce un’analisi breve, fattuale e in linguaggio semplice, generata esclusivamente a partire dai dati del prodotto. I verdetti — cosa è alto, cosa è un punto di forza, quali allergeni, quali diete — derivano da soglie fisse e pubblicate applicate nel codice; l’IA scrive il riassunto di due frasi e legge la lista degli ingredienti quando serve un giudizio. Nessun numero inventato, nessuna indicazione sulla salute e «sconosciuto» invece di una supposizione.

Analizzare un prodotto del catalogo

POST /v1/analyze/product accetta un food_id o un barcode (uno dei due), costa 4 crediti e risponde in una qualsiasi delle 6 lingue:

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

(Versione abbreviata: la risposta contiene anche nutrient_levels, il diets_detail completo, nova_group e flags.) Alcune cose utili da sapere sulla struttura:

highlights contiene solo punti di forza, warnings solo avvertenze — e uno stesso argomento non compare mai in entrambi. Un punto di forza significa che il prodotto soddisfa la condizione di una indicazione nutrizionale UE (a basso contenuto di sale: al massimo 0,3 g per 100 g; fonte di proteine: almeno il 12% dell’energia). Un’avvertenza è un livello «alto» secondo la FSA britannica, una porzione grande che supera il limite per porzione della FSA, oppure la presenza di caffeina, edulcoranti, alcol o olio di palma tra gli ingredienti.
allergens è riportato a parte: i 14 allergeni UE dichiarati in etichetta, come «contiene» e «può contenere», con una frase localizzata. status: "not_stated" significa che la scheda non ha dati sugli allergeni — controlla la confezione.
diets_detail indica da dove proviene ogni risposta: una dichiarazione in etichetta, un allergene dichiarato o la lista degli ingredienti. «Senza glutine» e «senza lattosio» sono yes solo con una dichiarazione in etichetta; una lista senza ingredienti con glutine dà no_known_source, perché un prodotto non certificato può comunque essere contaminato. diets mantiene la vista semplice yes / no / unknown — mostra unknown come un punto interrogativo, non con un’omissione silenziosa.
processing_level deriva dal gruppo NOVA registrato per il prodotto; solo quando non ce n’è nessuno viene valutato in base agli ingredienti (processing_basis: "model").
disclaimer accompagna ogni risposta. Mostralo — l’analisi è informativa, non un parere medico.

Le analisi sono memorizzate in cache per prodotto e lingua, quindi il primo chiamante paga la latenza di generazione e tutti gli altri ottengono una risposta istantanea — allo stesso prezzo di 4 crediti. cached: true ti dice in quale caso ti trovi.

Puoi vedere questo endpoint all’opera su qualsiasi pagina prodotto — il pannello «Analisi IA» è esattamente questa risposta.

Analizzare i tuoi dati di prodotto

E i prodotti che non sono nel catalogo — private label, nuovi lanci, SKU interni? POST /v1/analyze/custom (anch’esso 4 crediti) accetta i dati del prodotto nel corpo della richiesta ed esegue la stessa analisi:

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

Due regole mantengono onesto il risultato:

Un semplice nome viene rifiutato (422). Devi fornire gli ingredienti e/o almeno un valore nutrizionale per 100 g — altrimenti il modello non avrebbe nulla di fattuale da analizzare.
I valori implausibili vengono rifiutati, non corretti in silenzio. I campi dei nutrienti hanno limiti per 100 g (energia ≤ 900 kcal, grammi ≤ 100, sodio ≤ 10000 mg), e le chiavi di nutrienti sconosciute sono un errore anziché essere ignorate.

L’oggetto nutrients accetta i macronutrienti standard più una selezione di vitamine e minerali (vitamina C, D, B12, folati, E, calcio, ferro, potassio, magnesio, zinco) — fornisci più dati e i punti di forza diventano più precisi: se indichi i valori di calcio e ferro otterrai cose come «Source of calcium (150 mg per 100 g)» ogni volta che un valore raggiunge la soglia UE (15% dell’assunzione di riferimento per 100 g; il doppio per «ricco di»).

La risposta rispecchia quella dell’analisi del catalogo, con un input_hash al posto del food_id — input identici producono lo stesso hash, quindi le analisi ripetute degli stessi dati vengono servite dalla cache. C’è anche un campo facoltativo barcode: non viene analizzato, serve a segnalare il prodotto come uno che vorresti vedere aggiunto al catalogo.

Preferisci un modulo a un corpo JSON? Il playground ha questo stesso endpoint come modulo da compilare.

Note pratiche sull’integrazione

Lingua: passa lang (en, fr, es, de, it, bg) e l’intera analisi — riassunto, punti di forza, avvertenze, allergeni — torna in quella lingua. I verdetti sono identici in tutte le lingue per costruzione. Ogni lingua ha la propria cache.
Crediti: 4 crediti per chiamata, comprese le risposte dalla cache. Gli errori (richiesta non valida, errore del provider, prodotto sconosciuto) vengono rimborsati automaticamente — paghi solo le risposte.
Idempotenza: non c’è — un doppio invio sono due addebiti. Disabilita il pulsante mentre una richiesta è in corso.
Visualizzazione: la risposta è pensata per adattarsi direttamente all’interfaccia — paragrafo di riassunto, elenco dei punti di forza, elenco delle avvertenze, una riga di allergeni, quattro badge di dieta con la loro base, un’etichetta del livello di lavorazione. È proprio così che la mostrano le pagine prodotto del sito.
Testo dell’etichetta rovinato? Se la lista degli ingredienti del prodotto è illeggibile (spazi mancanti, caratteri rotti, TUTTO MAIUSCOLO), POST /v1/correct/product la ripara per tutti e l’analisi viene rigenerata dal testo corretto.

Provalo

Prendi una chiave API gratuita (20 crediti IA inclusi), apri la documentazione o prova i pannelli dal vivo su qualsiasi pagina prodotto.