API de reconocimiento de imágenes de alimentos

Qué endpoint para qué foto

Las cuatro operaciones reciben un único campo multipart/form-data llamado image. El servidor inspecciona los bytes, no el nombre del archivo: JPEG, PNG o WebP, de hasta 8 MB, o la subida se rechaza antes de que se ejecute ningún modelo. Las fotos se giran automáticamente según EXIF y se redimensionan a 1024 px en el lado más largo, así que una captura a resolución completa solo cuesta tiempo de subida.

POST /v1/vision/barcode decodifica EAN-13, EAN-8, UPC-A, UPC-E y Code-128 con visión por computador clásica y busca el código igual que GET /foods/barcode/{code}. El cuerpo del 200 es { barcode, product } con el registro completo del catálogo (id, name_default, brand, nutrition_summary y el resto). No se ejecuta ningún modelo de lenguaje, así que cuesta 0 créditos y se contabiliza como una llamada de datos.

Las otras tres son llamadas de IA. /vision/product lee el frontal de un envase y produce extracted { name, brand, quantity, lang, confidence } más matches ordenadas. /vision/label transcribe un panel nutricional en números por 100 g, ingredients_text, allergens y ración; un panel que solo imprime valores por ración se convierte a por 100 g en código cuando se imprime el tamaño de ración (basis per_100g, converted: true); cuando no, los campos por 100 son null y los números impresos vuelven bajo per_serving (basis per_serving). /vision/meal devuelve items[] de platos reconocidos con estimaciones de ración. Cada respuesta lleva request_id y cached.

• Una petición sin el campo image es un 422 Validation Error con details[].field = "image".

Cómo leer una respuesta de /vision/product

extracted.lang es el idioma leído en el envase (bg para una etiqueta en cirílico) y guía una búsqueda en el catálogo consciente del idioma. confidence va de 0 a 1 y condiciona esa búsqueda: el catálogo solo se consulta cuando confidence es al menos 0.3 y se leyó un nombre; en caso contrario matches está vacío.

matches contiene hasta 5 productos, el mejor primero, cada uno { score, product } con la misma forma FoodItem completa que un registro de la API de base de datos de alimentos. score se deriva de confidence y de la posición, así que la primera coincidencia lleva la propia confidence y cada una siguiente puntúa menos. Conserva matches[0].product.id; los ids son estables entre reimportaciones.

Un fallo se ve así, ante la foto de un producto pequeño: {"matches":[],"extracted":{"lang":"","name":"","brand":"","quantity":"","confidence":0},"request_id":"bcca8231-f335-4468-81bf-e587b614d9a4","cached":true}. Las cadenas vacías y confidence 0 significan que no se pudo leer ningún nombre; cached: true significa que esos mismos bytes ya se habían visto antes, y la llamada se cobró igualmente con 3 créditos.

Etiquetas y comidas: lectura frente a estimación

/vision/label es transcripción, no inferencia. energy_kcal, fat_g, saturated_fat_g, carbs_g, sugars_g, fiber_g, proteins_g y salt_g se leen tal como están impresos, y todo lo que no figura en la etiqueta vuelve null, nunca adivinado. Un código de barras legible en la misma foto se devuelve como extracted.barcode y se busca: un acierto rellena product con el FoodItem completo; si no, product es null.

/vision/meal es lo contrario, y su campo disclaimer lo dice. Cada elemento tiene dish, kind, portion_g_est y confidence, además de match cuando el plato se resolvió a un alimento genérico del USDA: id, name_default, per_100g { energy_kcal, proteins_g, carbs_g, fat_g } y estimated_kcal, que es per_100g.energy_kcal por portion_g_est entre 100. Los elementos son platos enteros (kind "dish": una hamburguesa, una lasaña) o los componentes separados de un plato (kind "component": arroz, pollo a la plancha, ensalada), nunca un plato junto con sus propias partes, de modo que estimated_total_kcal, la suma de los elementos que tienen una, no cuenta nada dos veces; es null cuando ningún elemento la tiene. La asociación usa alimentos genéricos en inglés (USDA FNDDS para platos tal como se comen, como lasaña, burritos o pad thai, y después USDA SR Legacy para ingredientes), así que match.name_default está en inglés sea cual sea la foto, y un elemento sin una coincidencia fiable recibe match: null en lugar de un alimento equivocado.

• Muestra el texto de disclaimer a los usuarios finales de las estimaciones de comidas; un plato con match: null cuesta igualmente los 5 créditos.

Créditos, reembolsos y el límite de tasa de visión

Los créditos se descuentan antes de la inferencia: 3 para product, 4 para label, 5 para meal. La asignación mensual se comparte entre todas las claves de la cuenta (Free 20, Starter 500, Pro 1300, Enterprise 3000) y se reinicia el día 1 del mes UTC. Cuando ya no puede cubrir una llamada, la pagan los créditos de los paquetes de recarga puntuales (comprados en la página de Facturación del panel, válidos 12 meses). Las respuestas de IA llevan X-Credits-Limit, X-Credits-Remaining (mensuales más recarga), X-Credits-Topup-Remaining y X-Credits-Reset; GET /v1/credits devuelve ambos saldos gratis.

Quedarse sin créditos es un 402, no un 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" }. Solo hay reembolso cuando la petición nunca llegó a una respuesta: imagen rechazada (413 o 422), campo ausente (422), fallo del proveedor (502, el mensaje termina en "You were not charged.") o visión desactivada (503). Los aciertos de caché se cobran a precio completo a propósito.

Las llamadas de IA tienen su propio límite por segundo, sin ráfaga: 1/s en Free y Starter, 2/s en Pro, 5/s en Enterprise por clave, y el triple en toda la cuenta. Las respuestas llevan X-RateLimit-Vision-Limit y X-RateLimit-Vision-Remaining; superarlo es un 429 con Retry-After: 1 y sin cobro, porque el limitador se ejecuta antes de la deducción.

El flujo de escaneo y la foto

Primero lo más barato. Decodifica el código de barras en el dispositivo y llama a la API de consulta de códigos de barras, o deja que /vision/barcode lo decodifique por 0 créditos. Solo cuando no hay código de barras, o la consulta devuelve 404, envía el frontal del envase a /vision/product. Con matches[0].product.id, obtén el desglose por 100 g de la API de nutrición o un veredicto en lenguaje sencillo de la API de análisis de alimentos con IA.

La calidad de la foto decide la confianza. Para /vision/product, encuadra el frontal del envase con nombre, marca y tamaño legibles y nada más en la imagen. Para /vision/label, coloca el panel plano, llena el encuadre con la tabla nutricional y el párrafo de ingredientes e incluye el código de barras si cabe. Para /vision/barcode la regla es el propio mensaje 422 del servidor: llena el encuadre con el código de barras, evita reflejos, mantenlo enfocado.

• Reintenta un 502 tras una breve espera; se te reembolsó. No reintentes un 200 de baja confianza; vuelve a hacer la foto.