API d'analyse IA des aliments

Désigner le produit, choisir la langue

POST /v1/analyze/product prend un corps JSON avec exactement un de food_id ou barcode (8 à 14 chiffres ; les variantes GTIN avec zéros de remplissage sont résolues) plus une lang facultative. Envoyez les deux ou aucun et vous obtenez un 422 indiquant "Provide exactly one of food_id or barcode", avec le crédit remboursé. Les chaînes vides comptent comme omises.

lang vaut en par défaut et accepte aussi fr, es, de, it et bg. Elle fixe la langue du texte, pas les verdicts : chaque verdict est calculé à partir de la fiche selon des règles fixes et formulé à partir d'un dictionnaire de phrases dans chaque langue, et les jugements du modèle sont rendus une fois par produit et partagés par toutes les langues, si bien qu'un produit ne peut pas être végan en anglais et pas en allemand. Les règles lisent les nutriments de la fiche, ses labels, ses tags d'allergènes et de traces et son groupe NOVA, les mêmes données que renvoient l'API de base de données alimentaire et l'API de nutrition. À partir d'une photo, l'API de reconnaissance d'images alimentaires vous donne d'abord le food_id.

Lire l'analyse, champ par champ

L'exemple est la réponse réelle pour le Nutella (code-barres 3017620422003, lang en). highlights ne contient que des points forts : un produit en obtient un quand il remplit la condition d'une allégation nutritionnelle du règlement UE 1924/2006, comme faible teneur en sel (au plus 0,3 g pour 100 g), source de protéines (au moins 12 % de l'énergie) ou riche en fibres (au moins 6 g). warnings ne contient que des points de vigilance : un nutriment au-dessus du seuil « élevé » de l'étiquetage avant de la UK FSA (sucres au-dessus de 22,5 g pour 100 g, ou de 11,25 g pour 100 ml pour les boissons), une grande portion qui dépasse la limite FSA par portion, ou de la caféine, des édulcorants, de l'alcool ou de l'huile de palme dans les ingrédients. Un sujet n'est jamais dans les deux, et chaque chiffre est la valeur propre de la fiche.

nutrient_levels donne les mêmes verdicts sous forme de données : lipides, acides gras saturés, sucres et sel, chacun low, medium ou high, avec basis per_100 ou per_portion. Un cola de 330 ml avec 10,6 g de sucres pour 100 ml est medium pour 100 ml mais high par canette, d'où son avertissement "High in sugars (35 g per serving)". allergens liste les 14 allergènes UE déclarés en contains et may_contain, avec le statut "not_stated" quand la fiche n'a pas de données d'allergènes, ce qui veut dire vérifier l'emballage, pas « aucun ».

diets_detail répond pour vegan, vegetarian, gluten_free et lactose_free avec une valeur et une justification (basis). Une allégation d'étiquette (végan, sans gluten, sans lactose, logos de certification) décide en premier ; un allergène déclaré ou un tag de viande exclut ensuite un régime ; sinon la réponse vient de la liste d'ingrédients. Sans gluten et sans lactose ne valent "yes" qu'avec une allégation d'étiquette : une liste d'ingrédients sans source de gluten donne "no_known_source", car un produit non certifié peut quand même être contaminé. diets garde l'ancienne forme yes/no/unknown, avec no_known_source rapporté comme unknown.

processing_level est le groupe NOVA sous forme de libellé — unprocessed (1), culinary_ingredient (2 : huiles, beurre, sucre), processed (3), ultra_processed (4) — d'après le groupe NOVA de la fiche (processing_basis "nova") ; c'est seulement quand la fiche n'en a pas qu'il est jugé à partir des ingrédients ("model"). per_serving est calculé à partir de la taille de portion de la fiche, ou null si aucune n'est enregistrée. disclaimer est une chaîne fixe ; affichez-la, car le texte est généré et décrit la fiche du catalogue, pas l'emballage que l'utilisateur a en main.

Crédits, cache et remboursements

Chaque appel coûte 4 crédits IA, pris sur une dotation mensuelle partagée par toutes les clés du compte (20 Free, 500 Starter, 1 300 Pro, 3 000 Enterprise ; réinitialisée le premier du mois UTC), puis sur les crédits de recharge ponctuels quand la dotation ne peut plus couvrir un appel. Ils sont débités avant l'inférence, et chaque réponse porte X-Credits-Limit, X-Credits-Remaining (mensuel plus recharge), X-Credits-Topup-Remaining et X-Credits-Reset.

Les analyses sont mises en cache par produit, langue et version d'analyse, liées au updated_at de la fiche : un produit réimporté ou corrigé est donc analysé à nouveau. Le source_updated_at de la réponse indique la version des données utilisée ; le updated_at de la fiche alimentaire vous dit si elle est toujours à jour. Une réponse en cache renvoie cached: true et coûte quand même 4 crédits : il n'y a pas de remboursement pour les réponses en cache sur les endpoints d'analyse. Mettez vous-même la réponse en cache, avec pour clé food_id et lang, si vous affichez souvent le même produit.

Les remboursements n'ont lieu que si rien n'a été produit : 404, 422, 502 (le message se termine par "You were not charged.") et 503. Un 401 ou un 429 ne touche jamais aux crédits.

Vos propres données produit : /analyze/custom

POST /v1/analyze/custom renvoie le même objet d'analyse pour un produit que vous décrivez vous-même : un article de marque de distributeur, un nouveau lancement, une étiquette que vous venez d'extraire. Le corps contient name (2 à 150 caractères) plus, en option, brand, category, quantity, ingredients (jusqu'à 3 000 caractères), un objet nutrients de valeurs pour 100 g et lang. Il n'y a ni champ de question libre ni profil, ni allégations d'étiquette ni tags d'allergènes : les régimes viennent donc des ingrédients, et sans gluten ou sans lactose vaut au mieux no_known_source.

Un nom seul donne un 422 : envoyez des ingrédients, au moins une valeur nutritionnelle, ou les deux, car le modèle n'a pas le droit d'inventer des valeurs nutritionnelles. nutrients est strict, avec dix-neuf clés nommées comme les colonnes du catalogue (energy_kcal, sugars_g, sodium_mg, calcium_mg, etc.) ; une clé inconnue donne un 422, et les valeurs hors plage sont rejetées plutôt que bornées.

La réponse contient input_hash au lieu de food_id, un SHA-256 de l'entrée canonisée : des données et une lang identiques donnent une réponse en cache, facturée comme les autres. Un barcode facultatif n'est pas analysé ; il signale seulement le produit comme un produit que vous voulez voir dans le catalogue.

Ajouter une langue : /translate/product

POST /v1/translate/product prend food_id ou barcode et une lang obligatoire, traduit le nom et le texte des ingrédients du produit, et écrit le résultat dans le catalogue sous forme de surcouche qui survit aux réimportations et est visible par tous les appelants comme une nouvelle entrée {lang, text} dans les tableaux name et ingredients de la fiche, et via name_localized dans la recherche. Les données d'étiquette déjà présentes dans cette langue ne sont jamais écrasées.

Ici, cached: true signifie que la langue existait déjà, et vos 4 crédits sont remboursés. force: true régénère une traduction que vous jugez mauvaise, mais seulement un texte issu d'une génération IA antérieure ; si le texte de la langue provient de l'étiquette ou d'une correction manuelle, vous obtenez un 422 avec les crédits remboursés. Une sortie peu fiable ou dangereuse n'est jamais stockée : l'appel renvoie 502 et vous n'êtes pas débité.

Corriger un texte d'étiquette abîmé : /correct/product

Le texte d'étiquette dans la langue du produit est parfois abîmé à la source : erreurs d'OCR, espaces manquants après les virgules, listes EN MAJUSCULES, caractères cassés comme "crème" pour "crème", ou un passage répété deux fois. POST /v1/correct/product le répare pour tout le monde, pour 4 crédits. La réparation ne peut changer que la forme : le code vérifie qu'aucun ingrédient, nombre, pourcentage ou numéro E n'a été ajouté ni retiré, que les virgules et les parenthèses sont restées à leur place, et que chaque allergène et sa mise en évidence ont survécu. Une réparation qui échoue n'est ni stockée ni facturée.

Quand c'est le contenu lui-même qui est faux, POST /v1/correct/product/photo prend une photo de l'étiquette et utilise la liste d'ingrédients qui y est lue comme preuve, pour 4 crédits. La lecture de la photo est la partie coûteuse : une photo lue mais inutilisable (aucune liste d'ingrédients visible, code-barres pas entièrement lisible, autre produit, ou lecture trop incertaine pour être fiable) répond 422 et est facturée comme /vision/label. Chaque correction conserve le texte précédent pour pouvoir revenir en arrière, se réapplique après les réimportations tant que la source en amont fournit encore le texte corrigé, et fait régénérer les traductions IA de l'ancien texte à leur prochaine demande. L'analyse du produit est régénérée elle aussi, puisque la fiche a changé.