KI-Lebensmittelanalyse API

Das Produkt adressieren, die Sprache wählen

POST /v1/analyze/product nimmt einen JSON-Body mit genau einem von food_id oder barcode (8 bis 14 Ziffern; GTIN-Varianten mit führenden Nullen werden aufgelöst) plus einem optionalen lang. Sendest du beide oder keines, bekommst du ein 422 mit „Provide exactly one of food_id or barcode“ und erstatteten Credits. Leere Strings gelten als weggelassen.

lang ist standardmäßig en und akzeptiert auch fr, es, de, it und bg. Es legt die Sprache des Textes fest, nicht die Urteile: Jedes Urteil wird nach festen Regeln aus dem Datensatz berechnet und aus einem Formulierungswörterbuch in jeder Sprache ausgedrückt, und die Beurteilungen des Modells werden einmal pro Produkt getroffen und von allen Sprachen geteilt — ein Produkt kann also nicht auf Englisch vegan und auf Deutsch nicht vegan sein. Die Regeln lesen Nährstoffe, Labels, Allergen- und Spuren-Tags und die NOVA-Gruppe des Datensatzes, dieselben Daten, die die Lebensmittel-Datenbank-API und die Nährwert-API liefern. Aus einem Bild bekommst du die food_id zuerst über die Lebensmittel-Bilderkennung-API.

Die Analyse lesen, Feld für Feld

Das Beispiel ist die echte Antwort für Nutella (Barcode 3017620422003, lang en). highlights sind nur Pluspunkte: Ein Produkt bekommt einen, wenn es die Bedingung einer Nährwertangabe nach EU-Verordnung 1924/2006 erfüllt, etwa wenig Salz (höchstens 0,3 g pro 100 g), Eiweißquelle (mindestens 12 % der Energie) oder hoher Ballaststoffgehalt (mindestens 6 g). warnings sind nur Warnhinweise: ein Nährstoff über dem „hoch“-Schwellenwert der UK-FSA-Frontkennzeichnung (Zucker über 22,5 g pro 100 g, oder über 11,25 g pro 100 ml bei Getränken), eine große Portion, die das FSA-Limit pro Portion überschreitet, oder Koffein, Süßungsmittel, Alkohol oder Palmöl in den Zutaten. Ein Thema ist nie beides, und jede Zahl ist der eigene Wert des Datensatzes.

nutrient_levels liefert dieselben Urteile als Daten: Fett, gesättigte Fette, Zucker und Salz, jeweils low, medium oder high, mit basis per_100 oder per_portion. Eine Cola mit 330 ml und 10,6 g Zucker pro 100 ml ist pro 100 ml medium, aber pro Dose high, sodass ihr Warnhinweis „High in sugars (35 g per serving)“ lautet. allergens listet die deklarierten EU-14-Allergene als contains und may_contain, mit status „not_stated“, wenn der Datensatz keine Allergendaten hat — das heißt, prüfe die Verpackung, nicht „keine“.

diets_detail beantwortet vegan, vegetarian, gluten_free und lactose_free mit value und basis. Eine Etikettenangabe (vegan, glutenfrei, laktosefrei, Zertifizierungslogos) entscheidet zuerst; ein deklariertes Allergen oder Fleisch-Tag schließt eine Diät als Nächstes aus; sonst stammt die Antwort aus der Zutatenliste. Glutenfrei und laktosefrei sind nur mit einer Etikettenangabe „yes“: Eine Zutatenliste ohne Glutenquelle ergibt „no_known_source“, weil ein nicht zertifiziertes Produkt dennoch kontaminiert sein kann. diets behält die ältere Form yes/no/unknown, wobei no_known_source als unknown gemeldet wird.

processing_level ist die NOVA-Gruppe als Label — unprocessed (1), culinary_ingredient (2: Öle, Butter, Zucker), processed (3), ultra_processed (4) — aus der NOVA-Gruppe des Datensatzes (processing_basis „nova“); nur wenn der Datensatz keine hat, wird sie aus den Zutaten beurteilt („model“). per_serving wird aus der Portionsgröße des Datensatzes berechnet, oder ist null, wenn keine hinterlegt ist. disclaimer ist ein fester String; zeige ihn an, denn der Text ist generiert und beschreibt den Katalogdatensatz, nicht die Packung in der Hand der Nutzerin.

Credits, Caching und Rückerstattungen

Jeder Aufruf kostet 4 KI-Credits aus einem monatlichen Kontingent, das alle Schlüssel des Kontos teilen (20 Free, 500 Starter, 1.300 Pro, 3.000 Enterprise; Reset am Ersten des Monats UTC), danach aus einmaligen Aufladungs-Credits, sobald das Kontingent einen Aufruf nicht mehr deckt. Die Abbuchung erfolgt vor der Inferenz, und jede Antwort trägt X-Credits-Limit, X-Credits-Remaining (monatlich plus Aufladung), X-Credits-Topup-Remaining und X-Credits-Reset.

Analysen werden pro Produkt, Sprache und Analyseversion gecacht, gebunden an das updated_at des Datensatzes, sodass ein neu importiertes oder korrigiertes Produkt frisch analysiert wird. Das source_updated_at der Antwort nennt die Datenversion, aus der sie erstellt wurde; das updated_at des Lebensmitteldatensatzes sagt dir, ob sie noch aktuell ist. Ein Treffer liefert cached: true und wird dennoch mit 4 Credits berechnet: Bei den analyze-Endpunkten gibt es keine Rückerstattungen für Cache-Treffer. Cache die Antwort selbst, mit food_id und lang als Schlüssel, wenn du dasselbe Produkt häufig zeigst.

Rückerstattungen gibt es nur, wenn nichts erzeugt wurde: 404, 422, 502 (die Meldung endet auf „You were not charged.“) und 503. Ein 401 oder 429 berührt nie die Credits.

Deine eigenen Produktdaten: /analyze/custom

POST /v1/analyze/custom liefert dasselbe Analyse-Objekt für ein Produkt, das du selbst beschreibst: einen Eigenmarken-Artikel, eine Neueinführung, ein Etikett, das du gerade extrahiert hast. Der Body trägt name (2 bis 150 Zeichen) plus optional brand, category, quantity, ingredients (bis zu 3.000 Zeichen), ein nutrients-Objekt mit Werten pro 100 g und lang. Es gibt keine Freitext-Frage- oder Profilfelder und keine Etikettenangaben oder Allergen-Tags, sodass Diäten aus den Zutaten stammen und glutenfrei oder laktosefrei höchstens no_known_source ist.

Ein name allein ist ein 422: Sende ingredients, mindestens einen Nährwert oder beides, denn das Modell darf keine Nährwertangaben erfinden. nutrients ist strikt, mit neunzehn Schlüsseln, die wie die Katalogspalten heißen (energy_kcal, sugars_g, sodium_mg, calcium_mg und so weiter); ein unbekannter Schlüssel ist ein 422, und Werte außerhalb des Bereichs werden abgelehnt statt begrenzt.

Die Antwort hat input_hash statt food_id, einen SHA-256 der kanonisierten Eingabe, sodass identische Daten und lang ein Cache-Treffer sind, der wie jeder andere berechnet wird. Ein optionaler barcode wird nicht analysiert; er markiert das Produkt nur als eines, das du im Katalog haben möchtest.

Eine Sprache ergänzen: /translate/product

POST /v1/translate/product nimmt food_id oder barcode und ein Pflichtfeld lang, übersetzt Namen und Zutatentext des Produkts und schreibt das Ergebnis als Overlay in den Katalog, das Reimporte übersteht und für jeden Aufrufer als neuer {lang, text}-Eintrag in den name- und ingredients-Arrays des Datensatzes sowie über name_localized in der Suche sichtbar ist. Etikettendaten, die schon in dieser Sprache vorliegen, werden nie überschrieben.

cached: true bedeutet hier, dass die Sprache schon existierte und deine 4 Credits erstattet werden. force: true erzeugt eine Übersetzung neu, die du für schlecht hältst, aber nur Text aus einem früheren KI-Lauf; stammt der Text der Sprache vom Etikett oder aus einer manuellen Korrektur, bekommst du ein 422 mit erstatteten Credits. Ausgabe mit niedriger Confidence oder unsichere Ausgabe wird nie gespeichert: Der Aufruf liefert 502, und dir wird nichts berechnet.

Defekten Etikettentext reparieren: /correct/product

Etikettentext in der eigenen Sprache des Produkts ist an der Quelle manchmal defekt: OCR-Fehler, fehlende Leerzeichen nach Kommas, Zutatenlisten in Großbuchstaben, kaputte Zeichen wie „crème“ statt „crème“ oder eine doppelt wiederholte Passage. POST /v1/correct/product repariert ihn für alle, für 4 Credits. Die Reparatur darf nur die Form ändern: Code prüft, dass keine Zutat, Zahl, kein Prozentwert und keine E-Nummer hinzugefügt oder entfernt wurde, dass Kommas und Klammern an ihrer Stelle blieben und dass jedes Allergen samt Hervorhebung erhalten blieb. Eine fehlgeschlagene Reparatur wird weder gespeichert noch berechnet.

Ist der Inhalt selbst falsch, nimmt POST /v1/correct/product/photo ein Foto des Etiketts und nutzt die daraus gelesene Zutatenliste als Beleg, für 4 Credits. Das Lesen des Fotos ist der teure Teil: Ein Foto, das gelesen, aber nicht verwendet werden kann (keine Zutatenliste sichtbar, der Barcode nicht vollständig lesbar, ein anderes Produkt oder eine zu unsichere Lesung), antwortet mit 422 und wird wie /vision/label berechnet. Jede Korrektur behält den vorherigen Text zum Zurücksetzen, wird nach Reimporten nur so lange neu angewendet, wie die Upstream-Quelle noch den korrigierten Text ausliefert, und sorgt dafür, dass sich die KI-Übersetzungen des alten Textes bei ihrer nächsten Anfrage neu erzeugen. Auch die Analyse des Produkts wird neu erzeugt, weil sich der Datensatz geändert hat.