Dalla foto ai dati alimentari: gli endpoint di visione

Quattro cose in cui si può trasformare una foto

Gli endpoint di visione trasformano una foto in dati alimentari strutturati. Ci sono quattro modalità, ognuna con il proprio endpoint e un prezzo in crediti IA (ogni piano — compreso Free — include una dotazione mensile):

Endpoint	Cosa fa	Crediti
POST /v1/vision/barcode	Decodifica un codice a barre da una foto e restituisce il prodotto corrispondente	0 (usa la tua quota giornaliera)
POST /v1/vision/product	Riconosce un prodotto dalla foto del fronte della confezione	3
POST /v1/vision/label	Legge un’etichetta nutrizionale: tabella, ingredienti, allergeni	4
POST /v1/vision/meal	Identifica i piatti in un piatto con stime delle porzioni	5

La decodifica dei codici a barre è pura visione artificiale — nessun modello di IA coinvolto — per questo non consuma crediti ed è conteggiata come una normale richiesta di dati.

Puoi provarli tutti e quattro nel browser, con la tua chiave e le tue foto, nel playground foto.

La forma della richiesta

Tutti e quattro accettano la stessa richiesta multipart — un solo campo image:

curl -X POST "https://foodbase.dev/v1/vision/product" \
  -H "X-API-Key: food_your_key_here" \
  -F "[email protected]"

Oppure da JavaScript:

async function vision(endpoint, file) {
  const form = new FormData();
  form.append("image", file);
  const res = await fetch(`https://foodbase.dev/v1/vision/${endpoint}`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (!res.ok) throw new Error(`Vision error: ${res.status}`);
  return res.json();
}

Le foto vengono normalizzate lato server (ridimensionate, EXIF rimosso) prima che qualunque modello di IA le tocchi, e le immagini non vengono mai memorizzate — la foto viene analizzata e scartata.

Riconoscimento dei prodotti

/vision/product estrae ciò che il modello riesce a vedere e lo confronta con il catalogo di 6,1 M di prodotti, restituendo corrispondenze ordinate per punteggio:

{
  "request_id": "…",
  "cached": false,
  "extracted": {
    "name": "Масло Краве",
    "brand": "…",
    "quantity": "250 g",
    "lang": "bg",
    "confidence": 0.95
  },
  "matches": [
    { "score": 0.98, "product": { "id": "…", "name_default": "…", "nutrition_summary": { } } }
  ]
}

Legge anche le confezioni in alfabeti non latini — le etichette in cirillico arrivano alle voci giuste del catalogo. Considera matches[0] come la risposta quando il suo punteggio è alto, e mostra una breve lista di scelta quando più corrispondenze hanno punteggi vicini.

Lettura delle etichette

/vision/label applica l’OCR a un pannello nutrizionale e restituisce gli stessi nomi di campo usati dal resto dell’API — più il testo degli ingredienti e gli allergeni rilevati:

{
  "extracted": {
    "energy_kcal": 539,
    "fat_g": 30.9,
    "saturated_fat_g": 10.6,
    "carbs_g": 57.5,
    "sugars_g": 56.3,
    "proteins_g": 6.3,
    "salt_g": 0.11,
    "ingredients_text": "Sugar, palm oil, hazelnuts 13%…",
    "allergens": ["milk", "nuts"],
    "product_name": "Nutella",
    "confidence": 0.97
  },
  "product": { "id": "…" }
}

I campi che l’etichetta non riporta tornano null — il modello non inventa mai numeri. Se l’etichetta include un codice a barre o il prodotto viene riconosciuto, product collega la scheda del catalogo.

Analisi dei pasti

/vision/meal identifica i piatti in un piatto, stima le porzioni e associa ogni piatto a un alimento generico, così ottieni stime delle calorie:

{
  "items": [
    {
      "dish": "grilled chicken breast",
      "portion_g_est": 150,
      "confidence": 0.9,
      "match": {
        "name_default": "Chicken breast, grilled",
        "per_100g": { "energy_kcal": 165, "proteins_g": 31, "carbs_g": 0, "fat_g": 3.6 },
        "estimated_kcal": 248
      }
    }
  ],
  "estimated_total_kcal": 612,
  "disclaimer": "Dish identification and portion sizes are AI estimates from a photo…"
}

Le porzioni ricavate da una sola foto sono stime — la risposta lo dice nel disclaimer, e dovrebbe farlo anche la tua interfaccia, idealmente con un modo rapido per l’utente di correggere i grammi.

Crediti, cache ed errori

• Ogni risposta IA include gli header X-Credits-Limit, X-Credits-Remaining e X-Credits-Reset — mostrali nella tua app così gli utenti non hanno mai sorprese.
• Le immagini identiche vengono messe in cache lato server, quindi le richieste ripetute tornano all’istante — allo stesso prezzo in crediti. Progetta la tua app in modo da mettere in cache i risultati sul client invece di reinviare la stessa foto.
• Non ti viene addebitato nulla quando la richiesta fallisce: immagini non valide o troppo grandi, errori del provider e codici a barre non trovati vengono tutti rimborsati automaticamente.
• Aspettati e gestisci 402 (crediti esauriti), 429 (limite di velocità al secondo per la visione — ogni piano ne ha uno) e 413 (immagine troppo grande).

Da dove cominciare

Prova le tue foto nel playground, poi leggi i contratti completi di richiesta/risposta nella documentazione. I 20 crediti mensili del piano gratuito bastano per provare una volta tutte e quattro le modalità.