About
This guide provides complete implementation details and best practices for integrating the Nutrition API into your applications. For detailed API specifications and data types, refer to the API Reference.Authentication: The code examples in this guide focus on the nutrition analysis functionality. For authentication implementation details, see the Authentication documentation. You’ll need to add Bearer token into the Authorization header to all API requests.
API Endpoints
The Nutrition API provides these endpoints for managing nutrition records:POST /nutrition_records/image— upload a food image for AI-powered nutritional analysisPOST /nutrition_records/ingredients/label— upload an image of a nutritional facts label to analyze itPOST /nutrition_records/manual— upload a manually created nutrition recordPATCH /nutrition_records/{id}— change the portion size for a nutrition record by IDPUT /nutrition_records/{id}— replace the nutrition record with a new oneGET /nutrition_records— retrieve a list of nutrition records by the time rangeGET /nutrition_records/{id}— retrieve a specific nutrition record by IDDELETE /nutrition_records/{id}— delete a specific nutrition record by ID
Image Preparation
For optimal image capture guidelines, see the Image Guidelines in the API overview.POST Request Body
Processing Modes
The processing mode is controlled by thewait_on_process parameter. The API supports two processing modes, each suited for a different use case:
Asynchronous Processing
Returns immediately and processes the image in the background. Ideal for user-facing applications where immediate feedback is important. See the Asynchronous Processing guide for complete implementation details, webhook configuration, and code examples.Synchronous Processing
Waits for complete analysis before responding. Best for batch processing, server-to-server integrations, or when you can handle longer response times: Request:Analysis Modes
precise(default) — uses advanced AI models for the highest accuracy and detailed analysisfast— uses optimized models for quicker processing with good accuracy
Localization
Providecountry_code and language_code for region-specific analysis:
- Region-specific food recognition
- Usage of local nutritional databases
- Translated ingredient names and descriptions
Including Optional Data
Control what data is included in the analysis:Selection of Nutritional Fields
You can control which nutritional fields are included in the analysis:include_nutrition_fields is omitted or empty, only four basic fields are included by default:
carbohydrate_genergy_kcalfat_total_gprotein_g
Response Body
Processing Status
Analysis of the nutrition record progresses through these states:- pending — analysis has been queued
- processing — an AI model is actively analyzing the image
- completed — analysis finished successfully with results
- failed — processing failed due to unidentifiable content or technical issues
- updated — an existing record was updated with a new serving size or fully replaced
status field.
status field with values completed, updated or failed. Always handle different response statuses in your application logic.
Error Scenarios
Processing Failures
These occur when the API successfully receives your request but the AI analysis fails. The response will have HTTP 200 status with"status": "failed".
When status is failed, check the failure_reason field for specific details:
-
Unidentifiable food items — image contains non-food objects or unclear food items
-
Poor image quality — blurry, dark, or low-resolution images
-
AI processing timeouts — although AI providers typically have fast Response Times, processing may occasionally take longer than expected due to reasons that cannot be foreseen.
To manage this, the upload process will time out if synchronous processing takes longer than 3 minutes and asynchronous processing takes longer than 5 minutes.
Once timeout occurs, the API will return HTTP status 200 and the body message with the
statusfield set tofailed:
Request Errors
These occur when there’s an issue with the request itself, returning non-200 HTTP status codes before analysis begins.-
Decoding Image Error — if the image is corrupted or improperly encoded, and therefore cannot be decoded, then HTTP 400 will be returned.
-
Invalid Image Format — nutrition AI supports JPEG, PNG, and WebP formats. When an image format is not supported, HTTP status code 400 will be returned.
-
Exceeding Image Size Limits — images larger than 10MB are not accepted, and API will return HTTP 413 status code.
Images larger than 11MB will be rejected by the gateway with HTTP 413 status code and the following error message.
-
Invalid Image URLs — when image is provided with the
body_urlparameter and the URL path is not found at the host, HTTP status code 422 will be returned.If thebody_urlparameter value is not a proper HTTP(S) URL, the following error will be given.
Nutrition Fields and Units
The names of nutrition fields are always lowercase and include units as suffix. Nutrition fields are not translated.Custom Nutrition Records
A full set of Nutrition AI endpoints allows sophisticated users to define their own nutrition records flexibly and precisely. Extracting nutrition details from nutrition facts labels lets users build up their own nutrition records from multiple ingredients. This is useful when users have existing nutritional data, follow recipes, or want to add custom items to the analyzed nutrition records.Creating Nutrition Records Manually
POST /nutrition_records/manual endpoint allows you to define a full nutrition record with all ingredients and their respective nutritional fields:
- Dish name and description including translation
- Serving size and unit
- Complete nutritional fields
- Individual ingredients with their nutritional breakdown
- Consumption timestamp
Updating Nutrition Records
Once a nutrition record exists (whether created manually or via AI analysis), you can update it in two ways:1. Changing Serving Size
UsePATCH /nutrition_records/{id} endpoint to adjust the portion size while maintaining the same nutritional ratios.
All ingredients and their respective nutritional fields will be automatically recalculated proportionally.
This allows you to easily adjust portion sizes while maintaining accurate nutritional information.
2. Replacing Full Record
UsePUT /nutrition_records/{id} to completely replace a record with new data, including different ingredients and nutritional values.
A response will include an input_type field with value manual to indicate that the record was fully replaced.
Getting Results
For asynchronous processing, use webhooks for real-time notifications. See the Asynchronous Processing Guide for complete webhook implementation details. If webhooks are not yet available, you can check status using theGET /nutrition_records/{id} endpoint.
Retrospectively, a list of all analyzed nutrition records can be retrieved using the GET /nutrition_records endpoint by providing the time range.
Deleting Results
A result can be deleted usingDETELE /nutrition_records/{id} endpoint by providing the record ID.
An HTTP 204 status code will be returned if successful, regardless if the record existed or not.
Best Practices
1. Choose the Right Processing Mode
- Asynchronous: For user-facing applications, mobile apps, and when you want immediate feedback
- Synchronous: For batch processing, server-to-server integrations, and when you can handle longer response times
2. Implement Proper Error Handling
- Handle network errors gracefully
- Provide meaningful error messages to users
- Implement retry logic for transient failures
Code Examples
Here are complete implementation examples in multiple programming languages:POST /nutrition_records API Reference.
