Analyse Nutrition

This endpoint allows you to upload food images for AI-powered nutritional analysis. The system uses advanced computer vision and machine learning models to identify ingredients, calculate nutritional values, and provide detailed food composition data.

Technical Requirements

Image Specifications

• Minimum size: 512x512 pixels
• Maximum size: 10MB when base64-encoded
• Supported formats: JPEG, PNG, WebP
• Input format: Base64-encoded string

Processing Workflow

The nutrition record analysis follows a multi-step process:

1. Image Upload & Validation: The system accepts base64-encoded images (JPEG, PNG, WebP) and validates format compatibility
2. AI Model Processing: Multiple AI models analyze the image concurrently
3. Ingredient Identification: Foods are identified using LANGUAL standard terminology for precise classification
4. Nutritional Analysis: Detailed nutritional breakdown is calculated per 100g/ml using established food databases
5. Translation (optional): Results can be translated to the specified language if different from English
6. Storage: Results are stored with configurable retention policies based on your application settings

Processing Modes

Asynchronous Processing (Default)

When wait_on_process is false or omitted, the API immediately returns with a pending status and processes the image in the background. This is recommended for better user experience, as processing typically takes 4–30 seconds, depending on image complexity and completeness of the nutrition fields requested.

Webhook Notifications

For asynchronous processing, you can optionally configure a webhook URL in Application to receive status updates when analysis completes. The system will make a POST request to your webhook URL with the complete nutrition record as JSON payload, regardless of whether processing succeeds or fails.

Webhook Security All webhook requests include HMAC SHA256 signature verification:

• Header: x-body-signature contains the hex-encoded HMAC signature
• Key: Uses your application’s webhook signature key (configured in admin console)
• Algorithm: HMAC-SHA256(webhook_signature_key, request_body)

Example webhook payload (POST request body):

{
  "application_id": 12345,
  "uid": "550e8400-e29b-41d4-a716-446655440000",
  "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "completed",
  "dish_name": "grilled chicken caesar salad",
  "dish_description": "chicken breast, grilled with romaine lettuce, parmesan cheese, and caesar dressing",
  "nutri_score": "B",
  "ingredients": [...],
  "uploaded_at": "2024-01-15T10:30:00Z"
}

Webhook Verification Examples:

import hmac
import hashlib
import json

def verify_webhook_signature(body, signature, webhook_key):
    """Verify the webhook signature"""
    expected_signature = hmac.new(
        webhook_key.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

# In your webhook handler
def handle_webhook(request):
    signature = request.headers.get('x-body-signature')
    body = request.body
    
    if not verify_webhook_signature(body, signature, WEBHOOK_KEY):
        return {'error': 'Invalid signature'}, 401
    
    nutrition_record = json.loads(body)
    # Process the nutrition record...

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, webhookKey) {
    const expectedSignature = crypto
        .createHmac('sha256', webhookKey)
        .update(body)
        .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(signature, 'hex'),
        Buffer.from(expectedSignature, 'hex')
    );
}

// Express.js webhook handler
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['x-body-signature'];
    
    if (!verifyWebhookSignature(req.body, signature, WEBHOOK_KEY)) {
        return res.status(401).send('Invalid signature');
    }
    
    const nutritionRecord = JSON.parse(req.body);
    // Process the nutrition record...
    res.status(200).send('OK');
});

Synchronous Processing

When wait_on_process is true, the API waits for complete processing before returning results. Use this when you need immediate results and can handle longer response times.

Processing Status

Nutrition records progress through these states:

• pending: Analysis has been queued
• processing: AI models are actively analyzing the image
• completed: Analysis finished successfully with results
• failed: Processing failed due to unidentifiable content or technical issues

Country and Language Context

Providing country_code significantly improves accuracy by:

• Enabling region-specific food recognition (e.g., distinguishing between American and European food varieties)
• Using local nutritional databases and standards
• Applying country-specific portion sizes and preparation methods
• Ensuring compliance with local food labeling regulations

The language_code parameter enables:

• Translated ingredient names and dish descriptions
• Localized nutritional terminology
• Better context for regional cuisine identification

Ingredients Analysis

When include_ingredients is enabled, the system provides:

• Ingredient identification using LANGUAL standard terminology
• Serving size estimation in metric units (grams for solids, milliliters for liquids)
• Per-ingredient nutritional breakdown calculated per 100g/ml
• Translated names when language localization is requested

Nutritional Fields

The API supports 29 different nutritional fields, from basic macronutrients to detailed micronutrients:

Default Fields

Provided if include_nutrition_fields is omitted or false.

• Energy (kcal)
• Protein (g)
• Total Fat (g)
• Carbohydrates (g)

Extended Nutritional Data

• Fats: Saturated, polyunsaturated, monounsaturated, trans fats
• Micronutrients: Fiber, sugars, cholesterol
• Minerals: Sodium, potassium, calcium, iron, magnesium, phosphorus, zinc
• Vitamins: A, C, D, E, K, B-complex vitamins

Additional Features

Nutri-Score Integration

Set include_nutri_score to true to receive the European Nutri-Score rating (A-E scale) that provides a quick nutritional quality assessment.

Dish Descriptions

Set include_dish_description to true to get detailed culinary descriptions using standardized food terminology, helpful for food logging and dietary tracking applications.

Image Optimization Guidelines

For optimal analysis results, guide your end users to:

1. Center the food: Capture a photo of the food you plan to eat, centering on the contents of your plate
2. Fill the frame: Ensure the meal occupies the majority of the image for better recognition
3. Remove distractions: Take off any packaging or utensils before snapping the photo
4. Clean background: Keep the background clutter-free; include only your plate or glass without additional items
5. Use proper lighting: Use natural or bright lighting to clearly capture details of the food
6. Optimal angle: Adjust the angle to minimize items obscuring each other and at a slight angle for the best perspective
7. Avoid filters: Avoid using filters or enhancements that might alter the food’s appearance

Processing Failures

When processing fails, the failure_reason field provides specific details about what prevented successful analysis:

• Unidentifiable food items: Image contains non-food objects or unclear food items
• Poor image quality: Blurry, dark, or low-resolution images
• Processing timeout: Complex images that exceed the specified max_duration_seconds
• Application limits: Nutrition scanning not enabled or retention policy not configured

When processing fails, the failure_reason field provides specific details about what prevented successful analysis.

Example Request and Response

Request

POST /nutrition_records request body:

{
  "body": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
  "country_code": "us",
  "language_code": "en",
  "include_ingredients": true,
  "include_dish_description": true,
  "include_nutri_score": true,
  "include_nutrition_fields": ["energy_kcal", "protein_g", "fat_total_g", "carbohydrate_g", "fiber_total_dietary_g"],
  "wait_on_process": false
}

Response (Asynchronous)

{
  "application_id": 12345,
  "uid": "550e8400-e29b-41d4-a716-446655440000",
  "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "processing",
  "uploaded_at": "2024-01-15T10:30:00Z"
}

The complete nutrition analysis will be sent to your webhook URL when processing finishes:

{
  "application_id": 12345,
  "uid": "550e8400-e29b-41d4-a716-446655440000",
  "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "completed",
  "dish_name": "grilled chicken caesar salad",
  "dish_description": "chicken breast, grilled with romaine lettuce, parmesan cheese, and caesar dressing",
  "nutri_score": "B",
  "ingredients": [
    {
      "name": "chicken breast, grilled",
      "serving_size": 150.0,
      "unit": "g",
      "nutritional_fields": {
        "energy_kcal": 165,
        "protein_g": 31,
        "fat_total_g": 3.6,
        "carbohydrate_g": 0,
        "fiber_total_dietary_g": 0
      }
    },
    {
      "name": "lettuce, romaine",
      "serving_size": 100.0,
      "unit": "g",
      "nutritional_fields": {
        "energy_kcal": 17,
        "protein_g": 1.2,
        "fat_total_g": 0.3,
        "carbohydrate_g": 3.3,
        "fiber_total_dietary_g": 2.1
      }
    },
    {
      "name": "cheese, parmesan, grated",
      "serving_size": 25.0,
      "unit": "g",
      "nutritional_fields": {
        "energy_kcal": 110,
        "protein_g": 10,
        "fat_total_g": 7.3,
        "carbohydrate_g": 1.0,
        "fiber_total_dietary_g": 0
      }
    }
  ],
  "uploaded_at": "2024-01-15T10:30:00Z"
}