Analyse IA des produits : des résumés que vos utilisateurs lisent vraiment

Le problème des données nutritionnelles brutes

Votre réponse d’API contient sugars_g: 56.3. Votre utilisateur veut savoir : est-ce beaucoup ? Combler ce fossé — transformer des chiffres et des listes d’ingrédients en quelque chose d’exploitable — est généralement l’étape où les applications de nutrition investissent lourdement ou jettent l’éponge.

Les endpoints d’analyse font cette étape à votre place : un seul appel renvoie une analyse courte, factuelle et en langage clair, générée strictement à partir des données du produit. Les verdicts — ce qui est élevé, ce qui est un point positif, quels allergènes, quels régimes — viennent de seuils fixes et publiés, appliqués dans le code ; l’IA rédige le résumé en deux phrases et lit la liste d’ingrédients quand un jugement est nécessaire. Aucun chiffre inventé, aucune allégation de santé, et « inconnu » plutôt qu’une supposition.

Analyser un produit du catalogue

POST /v1/analyze/product prend un food_id ou un barcode (l’un des deux), coûte 4 crédits et répond dans l’une des 6 langues :

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

(Version abrégée : la réponse contient aussi nutrient_levels, le diets_detail complet, nova_group et flags.) Quelques points utiles à savoir sur la structure :

highlights ne contient que des points positifs, warnings que des points de vigilance — et un même sujet n’apparaît jamais dans les deux. Un point positif signifie que le produit remplit la condition d’une allégation nutritionnelle de l’UE (« faible teneur en sel » : au plus 0,3 g pour 100 g ; « source de protéines » : au moins 12 % de l’énergie). Un point de vigilance correspond à un niveau « élevé » selon la FSA britannique, à une grande portion qui dépasse la limite par portion de la FSA, ou à la présence de caféine, d’édulcorants, d’alcool ou d’huile de palme dans les ingrédients.
allergens est présenté à part : les 14 allergènes de l’UE déclarés sur l’étiquette, en « contient » et « peut contenir », avec une phrase localisée. status: "not_stated" signifie que la fiche ne contient aucune donnée sur les allergènes — vérifiez l’emballage.
diets_detail indique d’où vient chaque réponse : une allégation de l’étiquette, un allergène déclaré ou la liste d’ingrédients. « Sans gluten » et « sans lactose » ne valent yes qu’avec une allégation sur l’étiquette ; une liste sans ingrédients contenant du gluten donne no_known_source, car un produit non certifié peut quand même être contaminé. diets conserve la vue simple yes / no / unknown — affichez unknown sous forme de point d’interrogation, pas par une omission silencieuse.
processing_level vient du groupe NOVA enregistré pour le produit ; ce n’est qu’en l’absence de groupe qu’il est évalué à partir des ingrédients (processing_basis: "model").
disclaimer accompagne chaque réponse. Affichez-le — l’analyse est informative, pas un avis médical.

Les analyses sont mises en cache par produit et par langue : le premier appelant paie la latence de génération, et tous les suivants obtiennent une réponse instantanée — au même prix de 4 crédits. cached: true vous indique dans quel cas vous êtes.

Vous pouvez voir cet endpoint en action sur n’importe quelle fiche produit — le panneau « Analyse IA » est exactement cette réponse.

Analyser vos propres données produit

Et les produits qui ne sont pas dans le catalogue — marques de distributeur, nouveautés, références internes ? POST /v1/analyze/custom (également 4 crédits) accepte les données du produit dans le corps de la requête et lance la même analyse :

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

Deux règles garantissent une sortie honnête :

Un simple nom est rejeté (422). Vous devez fournir les ingrédients et/ou au moins une valeur nutritionnelle pour 100 g — sinon le modèle n’aurait rien de factuel à analyser.
Les valeurs invraisemblables sont rejetées, pas corrigées en silence. Les champs nutritionnels ont des plafonds pour 100 g (énergie ≤ 900 kcal, grammes ≤ 100, sodium ≤ 10000 mg), et les clés de nutriments inconnues provoquent une erreur au lieu d’être ignorées.

L’objet nutrients accepte les macronutriments standards ainsi qu’une sélection de vitamines et minéraux (vitamine C, D, B12, folates, E, calcium, fer, potassium, magnésium, zinc) — fournissez-en davantage et les points positifs gagnent en précision : donnez des valeurs de calcium et de fer et vous obtiendrez des choses comme « Source of calcium (150 mg per 100 g) » dès qu’une valeur atteint le seuil de l’UE (15 % de l’apport de référence pour 100 g ; le double pour « riche en »).

La réponse reprend celle de l’analyse du catalogue, avec un input_hash à la place du food_id — des entrées identiques donnent le même hash, donc les analyses répétées des mêmes données tombent dans le cache. Il existe aussi un champ optionnel barcode : il n’est pas analysé, il signale simplement que vous aimeriez voir ce produit ajouté au catalogue.

Vous préférez un formulaire à un corps JSON ? Le playground propose exactement cet endpoint sous forme de formulaire à remplir.

Notes pratiques d’intégration

Langue : passez lang (en, fr, es, de, it, bg) et toute l’analyse — résumé, points positifs, points de vigilance, allergènes — revient dans cette langue. Les verdicts sont identiques dans toutes les langues par construction. Chaque langue a son propre cache.
Crédits : 4 crédits par appel, y compris pour les réponses en cache. Les échecs (requête invalide, erreur du fournisseur, produit inconnu) sont remboursés automatiquement — vous ne payez que les réponses.
Idempotence : il n’y en a aucune — un double envoi, ce sont deux débits. Désactivez votre bouton pendant qu’une requête est en cours.
Affichage : la réponse est conçue pour s’afficher directement dans une interface — paragraphe de résumé, liste de points positifs, liste de points de vigilance, une ligne d’allergènes, quatre badges de régime avec leur base, une étiquette de niveau de transformation. C’est précisément ainsi que les fiches produit du site l’affichent.
Texte d’étiquette illisible ? Si la liste d’ingrédients du produit est corrompue (espaces manquants, caractères cassés, TOUT EN MAJUSCULES), POST /v1/correct/product la répare pour tout le monde et l’analyse est régénérée à partir du texte corrigé.

À vous de jouer

Récupérez une clé d’API gratuite (20 crédits IA inclus), ouvrez la documentation, ou testez les panneaux en direct sur n’importe quelle fiche produit.