AI Food Analysis API

Address the product, pick the language

POST /v1/analyze/product takes a JSON body with exactly one of food_id or barcode (8 to 14 digits; zero-padded GTIN variants resolve) plus an optional lang. Send both or neither and you get a 422 reading "Provide exactly one of food_id or barcode", with the credit refunded. Empty strings count as omitted.

lang defaults to en and also accepts fr, es, de, it and bg. It sets the language of the text, not the verdicts: every verdict is computed from the record by fixed rules and worded from a phrase dictionary in each language, and the model's judgements are made once per product and shared by all languages, so a product cannot be vegan in English and not in German. The rules read the record's nutrients, labels, allergen and trace tags and NOVA group, the same data the Food Database API and the Nutrition API return. From a picture, the Food Image Recognition API gets you the food_id first.

Reading the analysis, field by field

The sample is the live response for Nutella (barcode 3017620422003, lang en). highlights are good points only: a product earns one when it meets the condition of an EU Regulation 1924/2006 nutrition claim, such as low salt (at most 0.3 g per 100 g), source of protein (at least 12% of energy) or high fibre (at least 6 g). warnings are watch-outs only: a nutrient above the UK FSA front-of-pack "high" threshold (sugars above 22.5 g per 100 g, or above 11.25 g per 100 ml for drinks), a large portion that crosses the FSA per-portion limit, or caffeine, sweeteners, alcohol or palm oil in the ingredients. A topic is never both, and every number is the record's own value.

nutrient_levels gives the same verdicts as data: fat, saturated fat, sugars and salt, each low, medium or high, with basis per_100 or per_portion. A 330 ml cola with 10.6 g of sugars per 100 ml is medium per 100 ml but high per can, so its warning reads "High in sugars (35 g per serving)". allergens lists the declared EU-14 allergens as contains and may_contain, with status "not_stated" when the record has no allergen data, which means check the package, not "none".

diets_detail answers vegan, vegetarian, gluten_free and lactose_free with a value and a basis. A label claim (vegan, gluten-free, lactose-free, certification logos) decides first; a declared allergen or meat tag rules a diet out next; otherwise the answer comes from the ingredient list. Gluten-free and lactose-free are "yes" only with a label claim: an ingredient list with no gluten source gives "no_known_source", because an uncertified product can still be contaminated. diets keeps the older yes/no/unknown shape, with no_known_source reported as unknown.

processing_level is the NOVA group as a label — unprocessed (1), culinary_ingredient (2: oils, butter, sugar), processed (3), ultra_processed (4) — from the record's NOVA group (processing_basis "nova"); only when the record has none is it judged from the ingredients ("model"). per_serving is computed from the record's serving size, or null when none is on file. disclaimer is a fixed string; show it, because the text is generated and it describes the catalog record, not the pack in the user's hand.

Credits, caching and refunds

Each call costs 4 AI credits from a monthly allowance shared by all keys on the account (20 Free, 500 Starter, 1,300 Pro, 3,000 Enterprise; reset on the first of the month UTC), then from one-time top-up credits once the allowance cannot cover a call. It is deducted before inference, and every response carries X-Credits-Limit, X-Credits-Remaining (monthly plus top-up), X-Credits-Topup-Remaining and X-Credits-Reset.

Analyses are cached per product, language and analysis version, tied to the record's updated_at, so a re-imported or corrected product is analyzed afresh. The response's source_updated_at names the data version it was made from; the food record's updated_at tells you whether it is still current. A hit returns cached: true and is still charged 4 credits: there are no refunds for cache hits on the analyze endpoints. Cache the response yourself, keyed on food_id and lang, if you show the same product often.

Refunds happen only when nothing was produced: 404, 422, 502 (the message ends "You were not charged.") and 503. A 401 or 429 never touches credits.

Your own product data: /analyze/custom

POST /v1/analyze/custom returns the same analysis object for a product you describe yourself: a private-label item, a new launch, a label you just extracted. The body carries name (2 to 150 characters) plus optional brand, category, quantity, ingredients (up to 3,000 characters), a nutrients object of per-100 g values and lang. There are no free-text question or profile fields, and no label claims or allergen tags, so diets come from the ingredients and gluten-free or lactose-free is at most no_known_source.

A name alone is a 422: send ingredients, at least one nutrient value, or both, because the model may not invent nutrition facts. nutrients is strict, with nineteen keys named like the catalog columns (energy_kcal, sugars_g, sodium_mg, calcium_mg and so on); an unknown key is a 422, and out-of-range values are rejected rather than clamped.

The response has input_hash instead of food_id, a SHA-256 of the canonicalized input, so identical data and lang is a cache hit, charged like any other. An optional barcode is not analyzed; it only flags the product as one you want in the catalog.

Adding a language: /translate/product

POST /v1/translate/product takes food_id or barcode and a required lang, translates the product's name and ingredients text, and writes the result into the catalog as an overlay that survives re-imports and is visible to every caller as a new {lang, text} entry in the record's name and ingredients arrays, and through name_localized in search. Label data already in that language is never overwritten.

cached: true here means the language already existed and your 4 credits are refunded. force: true regenerates a translation you consider bad, but only text from an earlier AI run; if the language's text is from the label or a manual fix, you get a 422 with the credits refunded. Low-confidence or unsafe output is never stored: the call returns 502 and you are not charged.

Fixing broken label text: /correct/product

Label text in the product's own language is sometimes broken at the source: OCR errors, missing spaces after commas, ALL-CAPS lists, broken characters such as "crème" for "crème", or a passage repeated twice. POST /v1/correct/product repairs it for everyone, for 4 credits. The repair may change the form only: code checks that no ingredient, number, percentage or E-number was added or removed, that commas and brackets stayed where they were, and that every allergen and its emphasis survived. A repair that fails is not stored and not charged.

When the content itself is wrong, POST /v1/correct/product/photo takes a photo of the label and uses the ingredient list read from it as evidence, for 4 credits. Reading the photo is the expensive part, so a photo that was read but cannot be used (no ingredient list visible, the barcode not readable in full, a different product, or a reading too uncertain to trust) answers 422 and is charged like /vision/label. Every correction keeps the previous text for revert, re-applies after re-imports only while the upstream source still ships the text that was fixed, and makes the AI translations of the old text regenerate on their next request. The analysis of the product regenerates too, because the record changed.