Lebensmittel-Bilderkennung API

Welcher Endpunkt für welches Foto

Alle vier Operationen nehmen ein multipart/form-data-Feld namens image. Der Server prüft die Bytes, nicht den Dateinamen: JPEG, PNG oder WebP bis 8 MB, sonst wird der Upload abgelehnt, bevor ein Modell läuft. Fotos werden anhand von EXIF automatisch gedreht und auf 1024 px an der längsten Kante verkleinert, eine Aufnahme in voller Auflösung kostet also nur Upload-Zeit.

POST /v1/vision/barcode dekodiert EAN-13, EAN-8, UPC-A, UPC-E und Code-128 mit klassischer Computer Vision und schlägt den Code genau wie GET /foods/barcode/{code} nach. Der 200-Body ist { barcode, product } mit dem vollständigen Katalogdatensatz (id, name_default, brand, nutrition_summary und der Rest). Es läuft kein Sprachmodell, daher kostet es 0 Credits und wird wie ein Datenaufruf gezählt.

Die anderen drei sind KI-Aufrufe. /vision/product liest eine Packungsvorderseite in extracted { name, brand, quantity, lang, confidence } plus gerankte matches. /vision/label überträgt eine Nährwerttabelle in Zahlen pro 100 g, ingredients_text, allergens und serving; eine Tabelle, die nur Werte pro Portion nennt, wird im Code auf pro 100 g umgerechnet, wenn die Portionsgröße aufgedruckt ist (basis per_100g, converted: true); ist sie es nicht, sind die Felder pro 100 null und die aufgedruckten Zahlen kommen unter per_serving zurück (basis per_serving). /vision/meal liefert items[] erkannter Gerichte mit Portionsschätzungen. Jede Antwort trägt request_id und cached.

• Eine Anfrage ohne das Feld image ist ein 422 Validation Error mit details[].field = "image".

Eine /vision/product-Antwort lesen

extracted.lang ist die auf der Packung gelesene Sprache (bg für ein kyrillisches Etikett) und steuert eine sprachbewusste Katalogsuche. confidence reicht von 0 bis 1 und steuert diese Suche: Der Katalog wird nur abgefragt, wenn confidence mindestens 0.3 beträgt und ein Name gelesen wurde; sonst ist matches leer.

matches enthält bis zu 5 Produkte, das beste zuerst, jeweils { score, product } in derselben vollständigen FoodItem-Form wie ein Datensatz der Lebensmittel-Datenbank-API. score leitet sich aus confidence und Rang ab, sodass der beste Treffer die confidence selbst trägt und jeder folgende Eintrag niedriger bewertet wird. Behalte matches[0].product.id; IDs bleiben über Reimporte hinweg stabil.

So sieht ein Fehlschlag aus, hier bei einem kleinen Produktfoto: {"matches":[],"extracted":{"lang":"","name":"","brand":"","quantity":"","confidence":0},"request_id":"bcca8231-f335-4468-81bf-e587b614d9a4","cached":true}. Leere Strings und confidence 0 heißen, dass kein Name gelesen werden konnte; cached: true heißt, dieselben Bytes waren schon einmal gesehen worden, und der Aufruf kostete dennoch 3 Credits.

Etiketten und Mahlzeiten: gelesen versus geschätzt

/vision/label ist Transkription, keine Schlussfolgerung. energy_kcal, fat_g, saturated_fat_g, carbs_g, sugars_g, fiber_g, proteins_g und salt_g werden so gelesen, wie sie aufgedruckt sind, und was nicht auf dem Etikett steht, kommt als null zurück, nie geraten. Ein lesbarer Barcode im selben Foto wird als extracted.barcode zurückgegeben und nachgeschlagen: Ein Treffer füllt product mit dem vollständigen FoodItem, sonst ist product null.

/vision/meal ist das Gegenteil, und sein Feld disclaimer sagt es auch. Jedes Item hat dish, kind, portion_g_est und confidence, dazu match, wenn das Gericht zu einem generischen USDA-Lebensmittel aufgelöst wurde: id, name_default, per_100g { energy_kcal, proteins_g, carbs_g, fat_g } und estimated_kcal, das ist per_100g.energy_kcal mal portion_g_est geteilt durch 100. Items sind entweder ganze Gerichte (kind "dish": ein Burger, eine Lasagne) oder die einzelnen Komponenten eines Tellers (kind "component": Reis, gegrilltes Hähnchen, Salat), nie ein Gericht zusammen mit seinen eigenen Teilen, sodass estimated_total_kcal, die Summe der Items, die eines haben, nichts doppelt zählt; es ist null, wenn kein Item eines hat. Der Abgleich nutzt englische generische Lebensmittel — USDA FNDDS für Gerichte, wie sie gegessen werden (Lasagne, Burritos, Pad Thai), dann USDA SR Legacy für Zutaten — daher ist match.name_default unabhängig vom Foto Englisch, und ein Item ohne sicheren Treffer bekommt match: null statt eines falschen Lebensmittels.

• Zeige den disclaimer-Text den Endnutzern von Mahlzeitenschätzungen; ein Gericht mit match: null kostet trotzdem die 5 Credits.

Credits, Rückerstattungen und das Vision-Rate-Limit

Credits werden vor der Inferenz abgebucht: 3 für product, 4 für label, 5 für meal. Das monatliche Kontingent wird von allen Schlüsseln des Kontos geteilt (Free 20, Starter 500, Pro 1.300, Enterprise 3.000) und am Ersten des UTC-Monats zurückgesetzt. Reicht es für einen Aufruf nicht mehr, bezahlen Credits aus einmaligen Aufladepaketen (auf der Abrechnungsseite des Dashboards gekauft, 12 Monate gültig) den Aufruf. KI-Antworten tragen X-Credits-Limit, X-Credits-Remaining (monatlich plus Aufladung), X-Credits-Topup-Remaining und X-Credits-Reset; GET /v1/credits liefert beide Guthaben kostenlos.

Aufgebraucht zu sein ist ein 402, kein 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" }. Rückerstattungen gibt es nur, wenn die Anfrage nie zu einer Antwort kam: abgelehntes Bild (413 oder 422), fehlendes Feld (422), Ausfall des Anbieters (502, die Meldung endet auf „You were not charged.“) oder deaktivierte Vision (503). Cache-Treffer werden bewusst zum vollen Preis berechnet.

KI-Aufrufe haben ein eigenes Sekundenlimit, ohne Burst: 1/s bei Free und Starter, 2/s bei Pro, 5/s bei Enterprise pro Schlüssel, und das Dreifache davon über das Konto. Antworten tragen X-RateLimit-Vision-Limit und X-RateLimit-Vision-Remaining; ein Überschreiten ist ein 429 mit Retry-After: 1 und ohne Abbuchung, weil der Limiter vor der Abbuchung läuft.

Der Scan-Ablauf und das Foto

Das Günstigste zuerst. Dekodiere den Barcode auf dem Gerät und rufe die Barcode-Abfrage-API auf, oder lass /vision/barcode ihn für 0 Credits dekodieren. Nur wenn es keinen Barcode gibt oder die Abfrage 404 liefert, sende die Packungsvorderseite an /vision/product. Mit matches[0].product.id hole die Aufschlüsselung pro 100 g von der Nährwert-API oder ein Urteil in einfacher Sprache von der KI-Lebensmittelanalyse-API.

Die Fotoqualität entscheidet über die Confidence. Für /vision/product bilde die Packungsvorderseite so ab, dass Name, Marke und Packungsgröße lesbar sind und sonst nichts im Bild ist. Für /vision/label lege die Tabelle flach hin, fülle den Bildausschnitt mit der Nährwerttabelle und dem Zutatenabsatz und nimm den Barcode mit auf, wenn er passt. Für /vision/barcode gilt die eigene 422-Meldung des Servers als Regel: den Barcode formatfüllend aufnehmen, Reflexionen vermeiden, scharfstellen.

• Ein 502 nach kurzer Wartezeit wiederholen; du wurdest erstattet. Ein 200 mit niedriger Confidence nicht wiederholen, sondern neu aufnehmen.