API de reconnaissance d'images alimentaires

Quel endpoint pour quelle photo

Les quatre opérations prennent un seul champ multipart/form-data nommé image. Le serveur analyse les octets, pas le nom de fichier : JPEG, PNG ou WebP, jusqu'à 8 Mo, sinon l'envoi est rejeté avant l'exécution de tout modèle. Les photos sont redressées d'après l'EXIF et redimensionnées à 1024 px sur le plus grand côté : une capture en pleine résolution ne coûte que du temps d'envoi.

POST /v1/vision/barcode décode EAN-13, EAN-8, UPC-A, UPC-E et Code-128 par vision par ordinateur classique et cherche le code exactement comme GET /foods/barcode/{code}. Le corps du 200 est { barcode, product } avec la fiche complète du catalogue (id, name_default, brand, nutrition_summary et le reste). Aucun modèle de langage n'intervient : il coûte 0 crédit et est décompté comme un appel de données.

Les trois autres sont des appels IA. /vision/product lit une face avant et produit extracted { name, brand, quantity, lang, confidence } plus des matches classés. /vision/label transcrit un tableau nutritionnel en valeurs pour 100 g, ingredients_text, allergens et serving ; un tableau qui n'imprime que des valeurs par portion est converti en pour 100 g par le code quand la taille de portion est imprimée (basis per_100g, converted: true) ; sinon, les champs pour 100 g valent null et les valeurs imprimées reviennent sous per_serving (basis per_serving). /vision/meal renvoie items[] avec les plats reconnus et des estimations de portion. Chaque réponse porte request_id et cached.

• Une requête sans champ image renvoie un 422 Validation Error avec details[].field = "image".

Lire une réponse de /vision/product

extracted.lang est la langue lue sur l'emballage (bg pour une étiquette en cyrillique) et pilote une recherche dans le catalogue adaptée à la langue. confidence va de 0 à 1 et conditionne cette recherche : le catalogue n'est interrogé que si confidence vaut au moins 0.3 et qu'un nom a été lu ; sinon matches est vide.

matches contient jusqu'à 5 produits, du meilleur au moins bon, chacun { score, product } dans la même forme FoodItem complète qu'une fiche de l'API de base de données alimentaire. score dérive de confidence et du rang : la meilleure correspondance porte la confidence elle-même et chaque entrée suivante a un score plus bas. Conservez matches[0].product.id ; les id sont stables d'une réimportation à l'autre.

Un échec ressemble à cette réponse à la photo d'un petit produit : {"matches":[],"extracted":{"lang":"","name":"","brand":"","quantity":"","confidence":0},"request_id":"bcca8231-f335-4468-81bf-e587b614d9a4","cached":true}. Des chaînes vides et confidence 0 signifient qu'aucun nom n'a pu être lu ; cached: true signifie que les mêmes octets avaient déjà été vus, et l'appel a tout de même coûté 3 crédits.

Étiquettes et repas : lu ou estimé

/vision/label est une transcription, pas une inférence. energy_kcal, fat_g, saturated_fat_g, carbs_g, sugars_g, fiber_g, proteins_g et salt_g sont lus tels qu'imprimés, et tout ce qui ne figure pas sur l'étiquette revient null, jamais deviné. Un code-barres lisible sur la même photo est renvoyé dans extracted.barcode et recherché : s'il est trouvé, product contient la FoodItem complète, sinon product vaut null.

/vision/meal fait l'inverse, et son champ disclaimer le dit. Chaque élément a dish, kind, portion_g_est et confidence, plus match quand le plat a été rapproché d'un aliment générique USDA : id, name_default, per_100g { energy_kcal, proteins_g, carbs_g, fat_g } et estimated_kcal, qui vaut per_100g.energy_kcal multiplié par portion_g_est divisé par 100. Les éléments sont soit des plats entiers (kind "dish" : un burger, des lasagnes), soit les composants séparés d'une assiette (kind "component" : riz, poulet grillé, salade), jamais un plat avec ses propres composants : estimated_total_kcal, la somme des éléments qui en ont un, ne compte donc rien deux fois ; il vaut null quand aucun élément n'en a. La correspondance utilise des aliments génériques en anglais — USDA FNDDS pour les plats tels que consommés (lasagne, burritos, pad thai), puis USDA SR Legacy pour les ingrédients — donc match.name_default est en anglais quelle que soit la photo, et un élément sans correspondance fiable reçoit match: null plutôt qu'un mauvais aliment.

• Affichez le texte du disclaimer aux utilisateurs finaux des estimations de repas ; un plat avec match: null coûte quand même 5 crédits.

Crédits, remboursements et limite de débit de la vision

Les crédits sont débités avant l'inférence : 3 pour product, 4 pour label, 5 pour meal. La dotation mensuelle est partagée par toutes les clés du compte (Free 20, Starter 500, Pro 1 300, Enterprise 3 000) et se réinitialise le premier du mois UTC. Quand elle ne peut plus couvrir un appel, les crédits des packs de recharge ponctuels (achetés sur la page Billing du tableau de bord, valables 12 mois) prennent le relais. Les réponses IA portent X-Credits-Limit, X-Credits-Remaining (mensuel plus recharge), X-Credits-Topup-Remaining et X-Credits-Reset ; GET /v1/credits renvoie gratuitement les deux soldes.

Être à court donne un 402, pas un 429 : { "error": "Insufficient credits", "message": "This call costs 3 credits and your free plan's monthly allowance of 20 is exhausted, with no top-up credits left. Buy more at https://foodbase.dev/dashboard/billing (they apply instantly), or wait for the reset on 2026-12-01.", "top_up_url": "https://foodbase.dev/dashboard/billing" }. Les remboursements n'ont lieu que si la requête n'a jamais abouti à une réponse : image rejetée (413 ou 422), champ manquant (422), défaillance du fournisseur (502, le message se termine par "You were not charged.") ou vision désactivée (503). Les réponses en cache sont facturées plein tarif, volontairement.

Les appels IA ont leur propre limite par seconde, sans rafale : 1/s sur Free et Starter, 2/s sur Pro, 5/s sur Enterprise par clé, et le triple pour l'ensemble du compte. Les réponses portent X-RateLimit-Vision-Limit et X-RateLimit-Vision-Remaining ; la dépasser donne un 429 avec Retry-After: 1 et aucun débit, car le limiteur s'exécute avant la déduction.

Le parcours de scan et la photo

Le moins cher d'abord. Décodez le code-barres sur l'appareil et appelez l'API de recherche par code-barres, ou laissez /vision/barcode le décoder pour 0 crédit. Seulement s'il n'y a pas de code-barres, ou si la recherche renvoie 404, envoyez la face avant de l'emballage à /vision/product. Avec matches[0].product.id, récupérez le détail pour 100 g via l'API de nutrition ou un avis en langage clair via l'API d'analyse IA des aliments.

La qualité de la photo détermine la confidence. Pour /vision/product, cadrez la face avant avec le nom, la marque et le format lisibles et rien d'autre dans le champ. Pour /vision/label, posez le tableau à plat, remplissez le cadre avec le tableau nutritionnel et le paragraphe des ingrédients, et incluez le code-barres s'il tient. Pour /vision/barcode, le message 422 du serveur fait foi : remplissez le cadre avec le code-barres, évitez les reflets, gardez-le net.

• Réessayez un 502 après une courte attente ; vous avez été remboursé. Ne renvoyez pas un 200 à faible confidence : reprenez plutôt la photo.