От снимка до хранителни данни: ендпойнтите за компютърно зрение

Четири неща, в които може да се превърне една снимка

Ендпойнтите за компютърно зрение превръщат снимка в структурирани хранителни данни. Има четири режима, всеки със собствен ендпойнт и собствена цена в AI кредити (всеки план — включително безплатният — идва с месечен лимит):

Ендпойнт	Какво прави	Кредити
POST /v1/vision/barcode	Декодира баркод от снимка и връща съвпадащия продукт	0 (отчита се в дневната ти квота)
POST /v1/vision/product	Разпознава продукт по снимка на предната страна на опаковката	3
POST /v1/vision/label	Разчита етикет с хранителни стойности: таблица, съставки, алергени	4
POST /v1/vision/meal	Разпознава ястията в чинията с оценка на порциите	5

Декодирането на баркод е чисто компютърно зрение — без AI модел — затова не струва кредити и се отчита като обикновена заявка за данни.

И четирите можеш да пробваш в браузъра, със собствения си ключ и снимки, във фото playground-а.

Формат на заявката

И четирите приемат една и съща multipart заявка — едно поле image:

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

Или от 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();
}

Снимките се нормализират на сървъра (смаляват се, EXIF данните се премахват), преди изобщо да стигнат до AI модел, и изображенията никога не се съхраняват — снимката се анализира и се изтрива.

Разпознаване на продукти

/vision/product извлича това, което моделът вижда, сравнява го с каталога от 6,1 млн. продукта и връща съвпадения, подредени по оценка:

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

Чете и опаковки, които не са на латиница — етикетите на кирилица водят до правилните записи в каталога. Приемай matches[0] за отговор, когато оценката му е висока, и показвай кратък списък за избор, когато няколко съвпадения са с близки оценки.

Разчитане на етикети

/vision/label разчита с OCR таблицата с хранителни стойности в същите имена на полета, които използва и останалата част от API-то — плюс текста на съставките и откритите алергени:

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

Полетата, които ги няма на етикета, се връщат като null — моделът никога не измисля числа. Ако етикетът съдържа баркод или продуктът бъде разпознат, product сочи към записа в каталога.

Анализ на ястия

/vision/meal разпознава ястията в чинията, оценява порциите и съпоставя всяко ястие с обща храна, така че получаваш оценка на калориите:

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

Порциите от една снимка са приблизителни — отговорът го казва в disclaimer, и твоят интерфейс трябва да го казва, в идеалния случай с бърз начин потребителят да коригира грамовете.

Кредити, кеширане и грешки

• Всеки AI отговор съдържа хедърите X-Credits-Limit, X-Credits-Remaining и X-Credits-Reset — показвай ги в приложението си, за да не изненадваш потребителите.
• Еднаквите изображения се кешират на сървъра, така че повторните заявки се връщат мигновено — на същата цена в кредити. Проектирай приложението си да кешира резултатите на клиента, вместо да изпраща една и съща снимка отново.
• Не плащаш, когато заявката е неуспешна: невалидни или прекалено големи изображения, грешки на доставчика и ненамерени баркодове се възстановяват автоматично.
• Очаквай и обработвай 402 (няма кредити), 429 (лимит на секунда за компютърно зрение — всеки план има такъв) и 413 (прекалено голямо изображение).

Откъде да започнеш

Поиграй си със собствените си снимки в playground-а, след това прочети пълните договори за заявки и отговори в документацията. 20-те месечни кредита в безплатния план стигат, за да пробваш и четирите режима по веднъж.