API de análisis de alimentos con IA

Identifica el producto y elige el idioma

POST /v1/analyze/product recibe un cuerpo JSON con exactamente uno de food_id o barcode (de 8 a 14 dígitos; las variantes de GTIN con ceros a la izquierda se resuelven) más un lang opcional. Si envías ambos o ninguno, obtienes un 422 que dice "Provide exactly one of food_id or barcode", con el crédito reembolsado. Las cadenas vacías cuentan como omitidas.

lang vale en por defecto y también acepta fr, es, de, it y bg. Fija el idioma del texto, no los veredictos: cada veredicto se calcula a partir del registro con reglas fijas y se redacta desde un diccionario de frases en cada idioma, y los juicios del modelo se hacen una vez por producto y se comparten entre todos los idiomas, así que un producto no puede ser vegano en inglés y no serlo en alemán. Las reglas leen los nutrientes del registro, las etiquetas, las etiquetas de alérgenos y trazas y el grupo NOVA, los mismos datos que devuelven la API de base de datos de alimentos y la API de nutrición. A partir de una imagen, la API de reconocimiento de imágenes de alimentos te da primero el food_id.

Cómo leer el análisis, campo a campo

La muestra es la respuesta real para Nutella (código de barras 3017620422003, lang en). highlights son solo puntos buenos: un producto gana uno cuando cumple la condición de una declaración nutricional del Reglamento (CE) 1924/2006 de la UE, como bajo en sal (como máximo 0,3 g por 100 g), fuente de proteínas (al menos el 12 % de la energía) o alto contenido en fibra (al menos 6 g). warnings son solo alertas: un nutriente por encima del umbral «alto» del etiquetado frontal de la FSA del Reino Unido (azúcares por encima de 22,5 g por 100 g, o por encima de 11,25 g por 100 ml en bebidas), una ración grande que supera el límite por ración de la FSA, o cafeína, edulcorantes, alcohol o aceite de palma en los ingredientes. Un tema nunca es ambas cosas, y cada número es el valor propio del registro.

nutrient_levels da los mismos veredictos como datos: grasas, grasas saturadas, azúcares y sal, cada uno low, medium o high, con basis per_100 o per_portion. Una cola de 330 ml con 10,6 g de azúcares por 100 ml es medium por 100 ml pero high por lata, así que su alerta dice "High in sugars (35 g per serving)". allergens lista los alérgenos EU-14 declarados como contains y may_contain, con status "not_stated" cuando el registro no tiene datos de alérgenos, lo cual significa revisa el envase, no «ninguno».

diets_detail responde vegan, vegetarian, gluten_free y lactose_free con un value y una basis. Decide primero una declaración de etiqueta (vegano, sin gluten, sin lactosa, logotipos de certificación); después un alérgeno declarado o una etiqueta de carne descarta una dieta; si no, la respuesta sale de la lista de ingredientes. Sin gluten y sin lactosa son "yes" solo con una declaración de etiqueta: una lista de ingredientes sin ninguna fuente de gluten da "no_known_source", porque un producto sin certificar aún puede estar contaminado. diets mantiene la forma antigua yes/no/unknown, con no_known_source informado como unknown.

processing_level es el grupo NOVA como etiqueta: unprocessed (1), culinary_ingredient (2: aceites, mantequilla, azúcar), processed (3), ultra_processed (4), a partir del grupo NOVA del registro (processing_basis "nova"); solo cuando el registro no tiene ninguno se juzga a partir de los ingredientes ("model"). per_serving se calcula a partir del tamaño de ración del registro, o es null cuando no consta ninguno. disclaimer es una cadena fija; muéstrala, porque el texto es generado y describe el registro del catálogo, no el envase que el usuario tiene en la mano.

Créditos, caché y reembolsos

Cada llamada cuesta 4 créditos de IA de una asignación mensual compartida por todas las claves de la cuenta (20 Free, 500 Starter, 1300 Pro, 3000 Enterprise; se reinicia el día 1 del mes UTC), y después de créditos de recarga puntuales cuando la asignación no puede cubrir una llamada. Se descuenta antes de la inferencia, y cada respuesta lleva X-Credits-Limit, X-Credits-Remaining (mensuales más recarga), X-Credits-Topup-Remaining y X-Credits-Reset.

Los análisis se cachean por producto, idioma y versión del análisis, ligados al updated_at del registro, así que un producto reimportado o corregido se analiza de nuevo. El source_updated_at de la respuesta nombra la versión de los datos a partir de la cual se hizo; el updated_at del registro del alimento te dice si sigue vigente. Un acierto devuelve cached: true y se cobra igualmente con 4 créditos: no hay reembolsos por aciertos de caché en los endpoints de análisis. Cachea tú la respuesta, con clave food_id y lang, si muestras el mismo producto con frecuencia.

Solo hay reembolso cuando no se produjo nada: 404, 422, 502 (el mensaje termina en "You were not charged.") y 503. Un 401 o un 429 nunca tocan los créditos.

Tus propios datos de producto: /analyze/custom

POST /v1/analyze/custom devuelve el mismo objeto de análisis para un producto que describes tú: un artículo de marca blanca, un lanzamiento nuevo, una etiqueta que acabas de extraer. El cuerpo lleva name (de 2 a 150 caracteres) más brand, category, quantity, ingredients (hasta 3000 caracteres), un objeto nutrients con valores por 100 g y lang, todos opcionales. No hay campos de pregunta libre ni de perfil, ni declaraciones de etiqueta ni etiquetas de alérgenos, así que las dietas salen de los ingredientes y sin gluten o sin lactosa es como mucho no_known_source.

Un nombre solo es un 422: envía ingredients, al menos un valor de nutriente, o ambos, porque el modelo no puede inventar datos nutricionales. nutrients es estricto, con diecinueve claves nombradas como las columnas del catálogo (energy_kcal, sugars_g, sodium_mg, calcium_mg y así sucesivamente); una clave desconocida es un 422, y los valores fuera de rango se rechazan en lugar de recortarse.

La respuesta tiene input_hash en lugar de food_id, un SHA-256 de la entrada canonicalizada, así que los mismos datos y lang son un acierto de caché, cobrado como cualquier otro. Un barcode opcional no se analiza; solo marca el producto como uno que quieres en el catálogo.

Añadir un idioma: /translate/product

POST /v1/translate/product recibe food_id o barcode y un lang obligatorio, traduce el nombre y el texto de ingredientes del producto y escribe el resultado en el catálogo como una capa superpuesta que sobrevive a las reimportaciones y es visible para todos los llamantes como una nueva entrada {lang, text} en los arrays name e ingredients del registro, y a través de name_localized en la búsqueda. Los datos de etiqueta que ya existan en ese idioma nunca se sobrescriben.

cached: true aquí significa que el idioma ya existía y tus 4 créditos se reembolsan. force: true regenera una traducción que consideras mala, pero solo texto de una ejecución de IA anterior; si el texto del idioma procede de la etiqueta o de una corrección manual, obtienes un 422 con los créditos reembolsados. Una salida de baja confianza o insegura nunca se guarda: la llamada devuelve 502 y no se te cobra.

Arreglar texto de etiqueta defectuoso: /correct/product

El texto de etiqueta en el idioma propio del producto a veces llega roto desde el origen: errores de OCR, espacios que faltan tras las comas, listas en MAYÚSCULAS, caracteres rotos como "crème" por "crème", o un pasaje repetido dos veces. POST /v1/correct/product lo repara para todos, por 4 créditos. La reparación solo puede cambiar la forma: el código comprueba que no se añadió ni se quitó ningún ingrediente, número, porcentaje ni número E, que las comas y los corchetes siguen donde estaban, y que sobrevivieron todos los alérgenos y su énfasis. Una reparación que falla no se guarda ni se cobra.

Cuando el contenido en sí es incorrecto, POST /v1/correct/product/photo recibe una foto de la etiqueta y usa como evidencia la lista de ingredientes leída de ella, por 4 créditos. Leer la foto es la parte cara, así que una foto que se leyó pero no se puede usar (sin lista de ingredientes visible, código de barras no legible por completo, un producto distinto o una lectura demasiado incierta para fiarse) responde 422 y se cobra como /vision/label. Cada corrección conserva el texto anterior para poder revertir, se vuelve a aplicar tras las reimportaciones solo mientras la fuente original siga enviando el texto que se corrigió, y hace que las traducciones por IA del texto antiguo se regeneren en su siguiente petición. El análisis del producto también se regenera, porque el registro cambió.