De la photo aux données alimentaires : les endpoints de vision

Quatre choses qu’une photo peut devenir

Les endpoints de vision transforment une photo en données alimentaires structurées. Il existe quatre modes, chacun avec son propre endpoint, chacun facturé en crédits IA (chaque offre — y compris Free — inclut une allocation mensuelle) :

Endpoint	Ce qu’il fait	Crédits
POST /v1/vision/barcode	Décode un code-barres depuis une photo, renvoie le produit correspondant	0 (utilise votre quota quotidien)
POST /v1/vision/product	Reconnaît un produit à partir de la photo de sa face avant	3
POST /v1/vision/label	Lit une étiquette nutritionnelle : tableau, ingrédients, allergènes	4
POST /v1/vision/meal	Identifie les plats d’une assiette avec des estimations de portions	5

Le décodage de code-barres relève de la pure vision par ordinateur — aucun modèle d’IA n’intervient — c’est pourquoi il ne consomme pas de crédits et est comptabilisé comme une requête de données classique.

Vous pouvez essayer les quatre dans le navigateur, avec votre propre clé et vos propres photos, sur le playground photo.

La forme de la requête

Les quatre acceptent la même requête multipart — un seul champ image :

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

Ou en 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();
}

Les photos sont normalisées côté serveur (réduites, EXIF supprimé) avant tout passage par un modèle d’IA, et les images ne sont jamais stockées — la photo est analysée puis supprimée.

Reconnaissance de produits

/vision/product extrait ce que le modèle voit et le met en correspondance avec le catalogue de 6,1 M de produits, en renvoyant des correspondances classées par score :

{
  "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": { } } }
  ]
}

Il lit aussi les emballages en alphabets non latins — les étiquettes cyrilliques aboutissent aux bonnes entrées du catalogue. Considérez matches[0] comme la réponse quand son score est élevé, et affichez une courte liste de choix quand plusieurs correspondances ont des scores proches.

Lecture d’étiquettes

/vision/label fait l’OCR d’un tableau nutritionnel vers les mêmes noms de champs que le reste de l’API — plus le texte des ingrédients et les allergènes détectés :

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

Les champs que l’étiquette n’indique pas reviennent à null — le modèle n’invente jamais de chiffres. Si l’étiquette comporte un code-barres ou si le produit est reconnu, product renvoie vers la fiche du catalogue.

Analyse de repas

/vision/meal identifie les plats d’une assiette, estime les portions et associe chaque plat à un aliment générique pour vous donner des estimations de calories :

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

Les portions déduites d’une seule photo sont des estimations — la réponse le précise dans disclaimer, et votre interface devrait le faire aussi, idéalement avec un moyen rapide pour l’utilisateur d’ajuster les grammes.

Crédits, cache et erreurs

• Chaque réponse IA contient les en-têtes X-Credits-Limit, X-Credits-Remaining et X-Credits-Reset — affichez-les dans votre application pour que vos utilisateurs ne soient jamais surpris.
• Les images identiques sont mises en cache côté serveur : les requêtes répétées reviennent instantanément — au même prix en crédits. Concevez votre application pour mettre les résultats en cache côté client plutôt que de renvoyer la même photo.
• Vous n’êtes pas facturé quand la requête échoue : images invalides ou trop volumineuses, erreurs du fournisseur et codes-barres introuvables sont tous remboursés automatiquement.
• Prévoyez et gérez 402 (plus de crédits), 429 (limite de débit de vision par seconde — chaque offre en a une) et 413 (image trop volumineuse).

Par où commencer

Essayez vos propres photos sur le playground, puis lisez les contrats complets de requête/réponse dans la documentation. Les 20 crédits mensuels de l’offre gratuite suffisent pour essayer chacun des quatre modes une fois.