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: the first analysis of a product is canonical, and other languages are translated from it with diets and processing_level copied verbatim. The model reads the record's name, brand, category, quantity, allergens, ingredients and nutrients row, 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 captured response for food 62ea12b8-b260-c288-5c38-3a4906f5d6dd (Coca-Cola, lang en) shows the shape. summary is at most 500 characters in the canonical language; highlights and warnings hold at most 8 strings each. Here warnings is "High in sugar (10.6 g/100 g)", "Contains added sugars (5.3 g/100 g)" and "Contains caffeine"; highlights includes "Low energy per 100 g (42 kcal)". Every number in those strings is quoted from the nutrients row; the prompt forbids inventing a value absent from the data.

diets has four keys, vegan, vegetarian, gluten_free and lactose_free, each exactly "yes", "no" or "unknown". "yes" and "no" appear only when ingredients or allergen data supports them; missing ingredients give "unknown", which means "do not filter on this", never "no". processing_level is one of unprocessed, minimally_processed, processed, ultra_processed or unknown, judged from the ingredients; the cola is ultra_processed. per_serving is one sentence in serving context when the record's quantity data allows it, otherwise null, as in the sample.

disclaimer is the fixed string "AI-generated from the product's label data. Informational only — not medical or dietary advice. Verify the physical label for allergens." Show it: 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 1 AI credit from a monthly allowance shared by all keys on the account (100 Free, 5,000 Starter, 15,000 Pro, 40,000 Enterprise; reset on the first of the month UTC). It is deducted before inference, and every response carries X-Credits-Limit, X-Credits-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. A hit returns cached: true, as in the sample, and is still charged 1 credit: 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.

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 to a record: /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 credit is 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 credit refunded. Low-confidence or unsafe output is never stored: the call returns 502 and you are not charged.